commit 9a39b8a941b74abd8940fd5a6b1cb64aa249fbd0 Author: Alexander Baranov Date: Mon Aug 24 14:39:09 2026 +0300 docs: baseline specification-only repository stewardship diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9cc8ab3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +.venv/ +__pycache__/ +*.py[cod] +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +dist/ +build/ +*.egg-info/ +coverage.xml +.coverage + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6d2e509 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,56 @@ +# Repository instructions + +## Purpose + +This repository defines Repository Stewardship: harness-neutral contracts, knowledge routing, templates and adoption practices for managing Git repositories with humans and AI agents. + +It currently contains specifications and runbooks. `repoctl`, executable handlers and an MCP server are planned interfaces, not implemented tools in this repository. + +## Start here + +1. Read `ops/contract.yaml` to identify the repository and authoritative content roots. +2. Read the small index in `kdb/kdb.yaml`. +3. Match the task to an exact topic intent. +4. Open only the documents and headings named by that topic's `data.readHints`. + +Do not load every design document by default. + +## Authority order + +- `docs/specification.md` is normative for fields, invariants and compatibility. +- `docs/adoption-runbook.md` is the canonical procedure for existing repositories. +- `docs/guide.md` explains the same model for people. +- `docs/research/` preserves earlier research and alternatives; it is not the current contract. + +If documents disagree, follow this order and record the discrepancy instead of silently merging meanings. + +## Repository boundaries + +- Keep domain-neutral standards here. +- Do not copy LXD, Docker, Antivirus or other domain handlers into this repository. +- Skills and MCP adapters must remain thin interfaces over the same model and future `repoctl` behavior. +- Do not claim an operation exists until a canonical handler and validation path exist. +- Keep canonical long-form documents under `docs/`; use deeper nesting only for a distinct authority class such as `docs/research/`. + +## Editing rules + +- Keep YAML examples machine-parseable. +- Use `stewardship.corsus.ru/v1alpha1`; do not introduce an alternative API group without a versioned migration. +- Keep Claude as the primary agent while preserving portable instructions in this file. +- A normative schema change must update affected examples, the human guide, KDB routing and adoption rules in the same change. +- Use Mermaid for architecture and workflow diagrams. +- Preserve unrelated user changes and do not modify other repositories unless the task explicitly includes them. +- Never place secrets, private keys, tokens or live credentials in contracts, KDB, examples or evidence. + +## Validation before completion + +- Parse Markdown frontmatter and every fenced YAML block. +- Validate `ops/contract.yaml` and `kdb/kdb.yaml` as YAML resources. +- Check KDB topic-to-document references and repo-relative paths. +- Check local Markdown links and balanced code fences. +- Statically check Mermaid block headers; render them when a Mermaid renderer is available. +- Confirm changed paths match the requested scope. + +## Self-hosting rule + +This repository should follow its own standard only where that adds discovery, safety or maintainability. Avoid placeholder directories, fake handlers, fictional capabilities and duplicated documentation created only for visual symmetry. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e8fa693 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,10 @@ +# CLAUDE.md + +@AGENTS.md + +## Claude-specific guidance + +- Treat `kdb/kdb.yaml` as the routing index, not as a request to read every linked document. +- For bootstrap or adoption work, produce assessment and proposed diff before writing. +- Ask only for decisions that cannot be established from repository evidence, such as ambiguous ownership or source-of-truth conflicts. +- Do not invoke future `repoctl` commands as if they already exist; follow the documented procedure manually until the CLI is implemented. diff --git a/README.md b/README.md new file mode 100644 index 0000000..de6b5da --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +# Repository Stewardship + +Этот репозиторий разрабатывает стандарт и будущий инструментарий для единообразной работы с Git-репозиториями при помощи людей и любых AI-агентов. + +Основная идея: каждый репозиторий сам сообщает, что он содержит, где лежит его реальный результат, какие знания нужны для конкретной задачи и какие действия допустимы. Claude является основным агентом, но модель не зависит от Claude, LLM, skill format или MCP. + +## Текущее состояние + +Сейчас здесь находятся спецификация, руководство и adoption runbook. CLI `repoctl`, handlers и MCP server ещё не реализованы; команды в документации определяют целевой интерфейс. + +| Точка входа | Назначение | +|---|---| +| `ops/contract.yaml` | машиночитаемый паспорт этого репозитория | +| `kdb/kdb.yaml` | маршрутизация знаний по intent | +| `CLAUDE.md` | основная точка входа Claude | +| `AGENTS.md` | переносимые инструкции для агентов | +| `docs/specification.md` | нормативная спецификация | +| `docs/guide.md` | объяснение модели для человека | +| `docs/adoption-runbook.md` | перевод существующих репозиториев на стандарт | +| `docs/research/` | исходные архитектурные исследования | + +## Как пользоваться содержимым + +```mermaid +flowchart LR + TASK["Задача"] --> CONTRACT["ops/contract.yaml"] + CONTRACT --> KDB["kdb/kdb.yaml"] + KDB --> TOPIC["Тема по exact intent"] + TOPIC --> SECTIONS["Только нужные документы и разделы"] + SECTIONS --> RESULT["Решение или proposed change"] +``` + +Для понимания модели начните с [руководства](docs/guide.md). Для реализации форматов используйте [спецификацию](docs/specification.md). Для подключения существующего репозитория следуйте [adoption runbook](docs/adoption-runbook.md). + +## Почему структура минимальна + +Репозиторий применяет собственную концепцию без декоративной унификации: + +- действующие документы собраны в одном content root `docs/`, а исходное исследование отделено в `docs/research/`; +- не созданы пустые `templates/`, `schemas/`, `src/` или `ops/handlers/`; +- не объявлены исполняемые operations, поскольку handlers ещё отсутствуют; +- template lineage не записан, потому что этот repository не был создан из готового versioned template; +- будущий код добавит собственный content root тогда, когда он действительно появится. + +## Ближайший практический этап + +1. Зафиксировать schemas и fixtures четырёх типов репозиториев. +2. Реализовать read-only `validate`, `discover`, `describe` и `context`. +3. Выполнить plan-only adoption для `Infra/LXD` и `Services/Antivirus`. +4. После пилотов реализовать `init`, `adopt` и тонкий Claude skill. diff --git a/docs/PLAN.md b/docs/PLAN.md new file mode 100644 index 0000000..987f089 --- /dev/null +++ b/docs/PLAN.md @@ -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//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 сохраняются без изменений. diff --git a/docs/adoption-runbook.md b/docs/adoption-runbook.md new file mode 100644 index 0000000..23914bb --- /dev/null +++ b/docs/adoption-runbook.md @@ -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. diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 0000000..8c54973 --- /dev/null +++ b/docs/guide.md @@ -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** — разные интерфейсы над одной моделью. diff --git a/docs/research/infrastructure-operations-architecture-options.md b/docs/research/infrastructure-operations-architecture-options.md new file mode 100644 index 0000000..0d545e0 --- /dev/null +++ b/docs/research/infrastructure-operations-architecture-options.md @@ -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 +├── / # 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": "", + "Services/Antivirus": "" + }, + "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//plan.json --confirm "APPLY " +opsctl verify --run +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. diff --git a/docs/specification.md b/docs/specification.md new file mode 100644 index 0000000..939d0b9 --- /dev/null +++ b/docs/specification.md @@ -0,0 +1,1425 @@ +--- +documentId: repository-stewardship-protocol +documentVersion: 0.2.0 +schemaApiVersion: stewardship.corsus.ru/v1alpha1 +status: draft +normative: true +language: ru +companionDocument: docs/guide.md +architectureSource: docs/research/infrastructure-operations-architecture-options.md +--- + +# Repository Stewardship Protocol: машинная спецификация + +## 0. Статус документа + +Этот документ задаёт минимальный расширяемый протокол описания и обслуживания Git-репозиториев. Он оптимизирован для чтения программами и AI-агентами. + +Нормативные слова `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT` и `MAY` имеют обычный смысл требований: + +- `MUST` — обязательно для заявленного уровня совместимости; +- `SHOULD` — рекомендуется; отклонение должно быть осознанным и объяснимым; +- `MAY` — необязательное расширение. + +Человекочитаемое объяснение находится в [guide.md](guide.md). Процедура подключения существующих репозиториев находится в [adoption-runbook.md](adoption-runbook.md). Исходное архитектурное исследование находится в [research/infrastructure-operations-architecture-options.md](research/infrastructure-operations-architecture-options.md). + +## 1. Цели и границы + +### 1.1. Цели + +Протокол MUST обеспечивать: + +1. единую точку обнаружения репозитория; +2. определение типа, назначения и владельца репозитория; +3. обнаружение штатных мест результата работы через `contentRoots`; +4. выборочную загрузку знаний по `intent`; +5. декларацию capabilities, requirements и bindings; +6. обнаружение разрешённых операций без копирования handlers в skills; +7. построение производного каталога и графа отношений; +8. независимость от LLM, agent harness, транспорта и языка handlers; +9. последующее добавление plan/apply/evidence и MCP без смены базовой модели. + +### 1.2. Не-цели первой реализации + +Первая реализация MUST NOT: + +- выполнять произвольные shell-строки из контракта; +- считать центральный каталог источником истины; +- хранить secret values в contract, KDB, context bundle или evidence; +- автоматически выполнять write-операции; +- навязывать одинаковое физическое дерево всем типам репозиториев; +- копировать domain-native artifacts в универсальный каталог `payload/`; +- требовать полноценный MCP server. + +### 1.3. Зафиксированные имена MVP + +Чтобы реализация не создавала параллельные соглашения, эта версия фиксирует: + +| Сущность | Каноническое имя | +|---|---| +| Модель/протокол | `Repository Stewardship` | +| API group | `stewardship.corsus.ru/v1alpha1` | +| CLI | `repoctl` | +| Contract | `ops/contract.yaml` | +| KDB по умолчанию | `kdb/kdb.yaml` | +| Переносимый agent entrypoint | `AGENTS.md` | +| Основной Claude entrypoint | `CLAUDE.md` | + +`Repository Stewardship` — имя модели и протокола; `repoctl` — имя локального CLI, а не второе имя модели. Ранний архитектурный документ использует рабочее имя `opsctl`; новая реализация SHOULD использовать только `repoctl`. Временный alias `opsctl` MAY существовать на этапе migration, но MUST вызывать тот же binary и не иметь отдельной семантики. + +## 2. Уровни совместимости + +| Уровень | Имя | Обязательные возможности | +|---|---|---| +| `L0` | Discoverable | валидный `ops/contract.yaml` | +| `L1` | Contextual | L0 + `AGENTS.md`, `CLAUDE.md`, валидный KDB entrypoint и выбор контекста по intent | +| `L2` | Operable | L1 + операции с каноническими handlers и input/output schemas | +| `L3` | Managed | L2 + immutable Plan, approvals, verification и RunEvidence | + +Цель MVP — полная реализация `L1`. Схемы `L2` и `L3` резервируются этим документом, но не должны блокировать MVP. + +## 3. Каноническое обнаружение + +### 3.1. Корень репозитория + +Корень репозитория определяется ближайшим родительским каталогом, содержащим `.git`. + +### 3.2. Канонические пути + +| Путь | Статус в L1 | Назначение | +|---|---|---| +| `ops/contract.yaml` | MUST | канонический `RepositoryContract` | +| `kdb/kdb.yaml` | SHOULD | рекомендуемый `KnowledgeBase`; допускается иной путь из contract | +| `AGENTS.md` | MUST | переносимые короткие инструкции для агентов | +| `CLAUDE.md` | MUST | основная точка входа Claude; SHOULD импортировать `AGENTS.md` | +| `ops/handlers/` | MAY в L1, MUST в L2 при наличии операций | канонические реализации операций | +| `ops/schemas/` | MAY в L1, SHOULD в L2 | repo-local input/output schemas | +| `docs/` | MAY | человекочитаемая документация | +| `ops/runs/` | MAY, обычно gitignored | локальные Plans и RunEvidence | + +Существующие репозитории MAY оставлять KDB и domain-native artifacts на прежних местах. Реальный путь MUST быть объявлен в contract. + +### 3.3. Правила путей + +Все пути в ресурсах: + +- MUST быть относительно корня репозитория; +- MUST использовать `/` как разделитель; +- MUST NOT начинаться с `/` или буквы диска; +- MUST NOT содержать сегмент `..`; +- MUST разрешаться внутри корня репозитория после нормализации; +- MAY указывать на ещё не созданный путь только при `repository.lifecycle: stub`. + +## 4. Общий envelope ресурсов + +Все YAML-ресурсы протокола используют общий верхний уровень: + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: RepositoryContract +metadata: + name: infra-lxd + title: LXD infrastructure + owners: + - infrastructure + labels: + domain: compute + annotations: {} +spec: + summary: Desired state and operations for managed LXD containers + repository: + type: infrastructure-config + lifecycle: production +``` + +### 4.1. Поля envelope + +| Поле | Тип | Обязательность | Правило | +|---|---|---|---| +| `apiVersion` | string | MUST | для этой версии ровно `stewardship.corsus.ru/v1alpha1` | +| `kind` | string | MUST | один из известных kinds | +| `metadata.name` | string | MUST | стабильный ID ресурса | +| `metadata.title` | string | SHOULD | человекочитаемое имя | +| `metadata.owners` | string[] | SHOULD | команды или пользователи, без секретов | +| `metadata.labels` | map[string]string | MAY | данные для выбора и группировки | +| `metadata.annotations` | map[string,any] | MAY | расширения, не влияющие на базовую семантику | +| `spec` | object | MUST | данные конкретного kind | + +### 4.2. Известные kinds + +| Kind | Владелец данных | Статус | +|---|---|---| +| `RepositoryContract` | репозиторий | authored, MVP | +| `KnowledgeBase` | репозиторий | authored, MVP | +| `CatalogIndex` | `repoctl` | derived, MVP | +| `ContextBundle` | `repoctl` | derived, MVP | +| `Plan` | planner | derived, post-MVP | +| `RunEvidence` | operation runner | derived, post-MVP | + +Вложенные `Operation`, `Capability`, `Requirement` и `Binding` в `v1alpha1` не являются отдельными kinds. Их стабильные IDs позволяют вынести их в отдельные ресурсы в будущей версии. + +### 4.3. Идентификаторы + +Локальный ID MUST соответствовать выражению: + +```text +^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$ +``` + +Рекомендуемый формат — `domain.action` или `domain.object`, например: + +```text +container.deploy +container.inspect +knowledge.lookup +repository.initialize +``` + +### 4.4. Ссылки на сущности + +Cross-repository ссылки используют следующие формы: + +```text +repo: +capability:/ +requirement:/ +binding:/ +operation:/ +topic:/ +``` + +Примеры: + +```text +repo:infra-lxd +capability:infra-lxd/container +requirement:services-antivirus/control-plane-container +operation:services-antivirus/control-plane.verify +``` + +## 5. RepositoryContract + +### 5.1. Минимальный валидный contract + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: RepositoryContract +metadata: + name: example-project + title: Example project + owners: + - example-team +spec: + summary: Example non-code project + repository: + type: project + lifecycle: active +``` + +### 5.2. Поля `spec` + +| Поле | Тип | L0 | Семантика | +|---|---|---|---| +| `summary` | string | MUST | одно краткое назначение репозитория | +| `repository` | object | MUST | классификация репозитория | +| `template` | object | MAY | происхождение от шаблона и готовность к migration | +| `agent` | object | SHOULD | точки входа для AI-агентов | +| `knowledge` | object | MAY | ссылка на `KnowledgeBase` | +| `contentRoots` | ContentRoot[] | SHOULD | штатные места результата работы | +| `provides` | Capability[] | MAY | предоставляемые возможности | +| `requires` | Requirement[] | MAY | требования к другим репозиториям | +| `bindings` | Binding[] | MAY | конкретные реализации requirements | +| `operations` | Operation[] | MAY | публичные разрешённые операции | + +### 5.3. `repository` + +```yaml +repository: + type: infrastructure-config + lifecycle: production + namespace: Infra + access: restricted +``` + +| Поле | Тип | Обязательность | Допустимые значения | +|---|---|---|---| +| `type` | string | MUST | `infrastructure-config`, `service-config`, `software`, `project` | +| `lifecycle` | string | MUST | `production`, `active`, `experimental`, `stub`, `archive`, `external` | +| `namespace` | string | MAY | организационный путь; не определяет type | +| `access` | string | MAY | `public`, `internal`, `restricted` | + +`type`, `lifecycle`, `namespace` и `access` являются независимыми осями классификации. + +### 5.4. `template` + +```yaml +template: + id: repository.infrastructure + version: 0.1.0 + source: repo:repository-templates + revision: 0123456789abcdef + answersRef: ops/template-answers.yaml + mode: adopted-overlay + managedPaths: + - ops/contract.yaml + - kdb/kdb.yaml +``` + +| Поле | Тип | Обязательность | Семантика | +|---|---|---|---| +| `id` | string | MUST, если `template` есть | стабильный ID шаблона | +| `version` | semver string | MUST | версия шаблона при последнем применении | +| `source` | entity ref или URI | SHOULD | источник шаблона | +| `revision` | string | SHOULD | immutable revision шаблона | +| `answersRef` | path | MAY | несекретные ответы для будущего update/migration | +| `mode` | string | SHOULD | `generated` или `adopted-overlay`; default `generated` | +| `managedPaths` | path[] | SHOULD для `adopted-overlay` | точная граница файлов, которыми управляет шаблон | + +`answersRef` MUST NOT указывать на файл с passwords, tokens, private keys или иными secret values. +При `mode: adopted-overlay` template update MUST изменять только `managedPaths`; отсутствие этого списка является validation warning. + +### 5.5. `agent` + +```yaml +agent: + primary: CLAUDE.md + portable: AGENTS.md +``` + +`primary` SHOULD быть `CLAUDE.md`, пока основным агентом является Claude. `portable` SHOULD быть `AGENTS.md`. + +### 5.6. `knowledge` + +```yaml +knowledge: + entrypoint: kdb/kdb.yaml +``` + +Если `knowledge.entrypoint` объявлен, файл MUST существовать и содержать `kind: KnowledgeBase`, кроме репозитория с `lifecycle: stub`. + +## 6. ContentRoot + +### 6.1. Формат + +```yaml +contentRoots: + - id: profiles-source + role: profiles + path: profiles-source + kind: directory + authority: source + writePolicy: managed + selector: "**/*.yaml" +``` + +### 6.2. Поля + +| Поле | Тип | Обязательность | Семантика | +|---|---|---|---| +| `id` | string | MUST | уникальный локальный ID | +| `role` | string | MUST | открытая семантическая роль | +| `path` | path | MUST | repo-relative файл или каталог | +| `kind` | string | MUST | `directory`, `file`, `file-set`, `manifest` | +| `authority` | string | MUST | `source`, `generated`, `observed`, `mirror`, `evidence` | +| `writePolicy` | string | SHOULD | `managed`, `read-only`, `generated` | +| `selector` | glob string | MAY | выбор объектов внутри `path` | +| `format` | string | MAY | MIME type или domain-specific format ID | +| `environments` | string[] | MAY | окружения, к которым относится root | +| `generatedFrom` | string[] | MAY | IDs roots или entity refs источников | + +`role` является открытым словарём. Инструменты MUST сохранять неизвестные роли и MAY обрабатывать их как generic content. + +### 6.3. Рекомендуемые роли + +| Repository type | Рекомендуемые роли | +|---|---| +| `infrastructure-config` | `desired`, `inventory`, `profiles`, `stacks`, `overlays`, `observed`, `evidence` | +| `service-config` | `service-definition`, `policies`, `acceptance`, `runbooks`, `deployments` | +| `software` | `source`, `tests`, `build`, `packages`, `deployment` | +| `project` | `deliverables`, `sources`, `working`, `decisions`, `datasets`, `archive` | + +## 7. Capability, Requirement и Binding + +### 7.1. Capability + +Capability описывает тип возможности провайдера, а не конкретный runtime resource. + +```yaml +provides: + - id: container + capability: compute.lxd-container + summary: Managed LXD system container + parametersSchema: ops/schemas/lxd-container.parameters.schema.json +``` + +| Поле | Тип | Обязательность | +|---|---|---| +| `id` | string | MUST | +| `capability` | string | MUST | +| `summary` | string | SHOULD | +| `parametersSchema` | path | MAY | + +### 7.2. Requirement + +Requirement принадлежит consumer repository. + +```yaml +requires: + - id: control-plane-container + capability: compute.lxd-container + summary: Container for antivirus control plane + constraints: + cpu: 4 + memory: 8GiB + networkZone: services + acceptance: + - operation:services-antivirus/control-plane.verify +``` + +| Поле | Тип | Обязательность | +|---|---|---| +| `id` | string | MUST | +| `capability` | string | MUST | +| `summary` | string | SHOULD | +| `constraints` | object | MAY | +| `preferredProviders` | repo refs[] | MAY | +| `acceptance` | operation refs[] | SHOULD | + +`preferredProviders` MUST NOT превращаться в неявную инфраструктурную реализацию внутри service repository. + +### 7.3. Binding + +Binding принадлежит provider repository и связывает requirement с конкретным target. + +```yaml +bindings: + - id: antivirus-control-plane + requirement: requirement:services-antivirus/control-plane-container + target: lxd://drweb/dwcp + status: active + evidenceRef: run-evidence://2026-08-24/antivirus-control-plane +``` + +| Поле | Тип | Обязательность | Допустимые значения | +|---|---|---|---| +| `id` | string | MUST | локальный ID | +| `requirement` | requirement ref | MUST | существующее consumer requirement | +| `target` | URI-like string | MUST | domain-specific immutable/stable locator | +| `status` | string | MUST | `proposed`, `active`, `failed`, `retired` | +| `evidenceRef` | string | SHOULD для `active` | ссылка на verification evidence | + +Binding со статусом `active` SHOULD иметь успешное provider verification и consumer acceptance. + +## 8. Intent + +Intent описывает цель пользователя, а не команду реализации. + +### 8.1. Формат + +Intent ID использует тот же формат ID и SHOULD иметь форму `domain.action`: + +```text +repository.initialize +repository.describe +knowledge.lookup +container.deploy +container.inspect +service.verify +``` + +### 8.2. Использование + +Intent MAY быть объявлен: + +- в `KnowledgeBase.spec.topics[].intents`; +- в `RepositoryContract.spec.operations[].intents`; +- во входе `repoctl context`; +- в `Plan.spec.intent`. + +Intent MUST NOT содержать shell-команду, hostname, token или изменчивый runtime fact. + +## 9. Operation + +### 9.1. Формат + +```yaml +operations: + - id: container.inspect + title: Inspect LXD containers + intents: + - container.inspect + - container.deploy + phase: inspect + effect: read-only + risk: low + execution: + handler: ops/handlers/lxd.py + argv: + - inspect + inputSchema: ops/schemas/container-inspect.input.schema.json + outputSchema: ops/schemas/container-inspect.output.schema.json + preconditions: + - contract.valid +``` + +### 9.2. Поля + +| Поле | Тип | Обязательность | Семантика | +|---|---|---|---| +| `id` | string | MUST | стабильный локальный operation ID | +| `title` | string | SHOULD | название для человека | +| `intents` | string[] | SHOULD | цели, для которых операция релевантна | +| `phase` | string | MUST | фаза стандартного lifecycle | +| `effect` | string | MUST | тип побочного эффекта | +| `risk` | string | MUST | уровень риска | +| `execution` | object | MUST для L2 | канонический handler и статические argv | +| `inputSchema` | path | SHOULD для L2 | JSON Schema входа | +| `outputSchema` | path | SHOULD для L2 | JSON Schema результата | +| `preconditions` | string[] | MAY | стабильные IDs проверяемых условий | +| `approval` | string | MAY | `never`, `on-write`, `always` | + +### 9.3. `phase` + +Допустимые значения: + +```text +describe +inspect +snapshot +validate +diff +plan +apply +verify +reconcile +rollback +``` + +### 9.4. `effect` + +| Effect | Значение | +|---|---| +| `read-only` | не изменяет repo или external systems | +| `local-write` | пишет только локальные artifacts внутри разрешённого рабочего каталога | +| `external-write` | изменяет внешнюю систему | +| `disruptive` | может вызвать временное нарушение сервиса | +| `destructive` | удаляет или необратимо заменяет данные/ресурсы | + +### 9.5. `risk` + +Допустимые значения: `low`, `medium`, `high`, `critical`. + +### 9.6. Execution safety + +Для `L2`: + +- `execution.handler` MUST быть repo-relative path; +- `execution.argv` MUST быть массивом статических токенов; +- contract MUST NOT содержать shell pipelines, redirections или command substitution; +- `repoctl` MUST запускать handler без shell interpolation; +- dynamic input MUST передаваться структурированно после schema validation; +- effect `external-write`, `disruptive` и `destructive` MUST требовать plan и approval на уровне `L3`. + +Точный общий handler ABI откладывается до L2. До его утверждения adapters MAY вызывать существующие handlers через repo-specific implementation, но публичная семантика operation ID MUST оставаться стабильной. + +## 10. KnowledgeBase + +### 10.1. Минимальный KDB + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: KnowledgeBase +metadata: + name: example-project-kdb + title: Example project knowledge base + owners: + - example-team +spec: + repository: repo:example-project + defaultLanguage: ru + topics: [] + documents: [] +``` + +### 10.2. Поля `spec` + +| Поле | Тип | Обязательность | Семантика | +|---|---|---|---| +| `repository` | repo ref | MUST | владелец KDB | +| `defaultLanguage` | BCP-47-like string | SHOULD | язык по умолчанию | +| `topics` | Topic[] | MUST | маршруты знаний по intent | +| `documents` | KnowledgeDocument[] | MUST | реестр локальных и внешних источников | + +### 10.3. Topic + +```yaml +topics: + - id: container-deployment + title: Container deployment + summary: Canonical local process for creating an LXD container + intents: + - container.deploy + keywords: + - lxd + - container + - profile + priority: 80 + documents: + - container-deployment-howto + - canonical-lxd-reference + relatedTopics: + - network-attachment + data: + constraints: + requirePlan: true + requireProfileSource: true +``` + +| Поле | Тип | Обязательность | Семантика | +|---|---|---|---| +| `id` | string | MUST | уникальный topic ID | +| `title` | string | SHOULD | название | +| `summary` | string | MUST | краткое содержание | +| `intents` | string[] | MUST | exact-match intents | +| `keywords` | string[] | MAY | вспомогательный поиск | +| `priority` | integer 0..100 | MAY | default `50` | +| `documents` | string[] | MAY | IDs документов | +| `relatedTopics` | string[] | MAY | локальные topic IDs | +| `data` | object | MAY | проверенные машиночитаемые факты и constraints | + +`data` MUST NOT содержать secrets или неограниченный binary/base64 content. + +### 10.4. KnowledgeDocument + +```yaml +documents: + - id: canonical-lxd-reference + title: Canonical LXD documentation snapshot + role: vendor-source + path: kdb/vendor/lxd/reference.html + mediaType: text/html + authority: vendor + status: verified + provenance: + uri: https://documentation.ubuntu.com/lxd/ + vendor: Canonical + version: "5.x" + retrievedAt: 2026-08-20T10:00:00Z + sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef + license: vendor-terms + freshness: + verifiedAt: 2026-08-20T10:00:00Z + expiresAt: 2026-11-20T10:00:00Z + verificationOperation: operation:infra-lxd/knowledge.validate +``` + +| Поле | Тип | Обязательность | Семантика | +|---|---|---|---| +| `id` | string | MUST | уникальный document ID | +| `title` | string | SHOULD | название | +| `role` | string | MUST | документарная роль | +| `path` | path | `path` XOR `uri` | локальный источник | +| `uri` | URI | `path` XOR `uri` | внешний источник без локальной копии | +| `mediaType` | string | SHOULD | MIME type | +| `authority` | string | MUST | природа авторитетности | +| `status` | string | MUST | состояние проверки | +| `provenance` | object | SHOULD для vendor/derived/observed | происхождение | +| `freshness` | object | SHOULD для verified/observed | актуальность и способ проверки | + +Допустимые `role`: + +```text +tutorial +how-to +reference +explanation +runbook +vendor-source +evidence +``` + +Допустимые `authority`: + +```text +vendor +local-canonical +observed +derived +manual +``` + +Допустимые `status`: + +```text +verified +manual +draft +stale +``` + +### 10.5. Provenance rules + +- `provenance.sha256`, если указан, MUST быть lowercase SHA-256 из 64 hex symbols. +- `status: verified` SHOULD иметь `freshness.verifiedAt`. +- Если `freshness.expiresAt <= currentTime`, consumer MUST считать документ stale независимо от authored `status` и MUST вывести warning. +- Локальная копия vendor source SHOULD иметь `provenance.uri`, version/date и hash. +- Локальная копия MUST храниться только если это допускают лицензия и правила доступа. +- Derived knowledge SHOULD ссылаться на исходные documents через extension `metadata.annotations.derivedFrom` или будущую версию схемы. + +### 10.6. Выбор контекста по intent + +`repoctl context --intent --repo ` MUST: + +1. загрузить и валидировать contract; +2. загрузить KDB по `knowledge.entrypoint`; +3. выбрать topics, где `topic.intents` содержит точное значение intent; +4. отсортировать topics по `priority DESC`, затем `id ASC`; +5. включить `topic.data` и ссылки на documents; +6. убрать повторяющиеся documents по ID; +7. пометить отсутствующие и stale documents warnings; +8. включить operations, где `operation.intents` содержит intent; +9. включить относящиеся к repo `contentRoots`; +10. не загружать `relatedTopics` без явного `--include-related`; +11. соблюдать заданный byte/token budget детерминированным образом. + +Keyword search MAY дополнять exact intent routing, но MUST NOT вытеснять его в MVP. + +## 11. CatalogIndex + +`CatalogIndex` является полностью производным ресурсом и MUST NOT редактироваться вручную. + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: CatalogIndex +metadata: + name: local-git-catalog +spec: + generatedAt: 2026-08-24T12:00:00Z + roots: + - C:/Users/example/Git + repositories: + - ref: repo:infra-lxd + path: Infra/LXD + type: infrastructure-config + lifecycle: production + contractHash: sha256:0123456789abcdef + relations: + - from: repo:services-antivirus + type: owns + to: requirement:services-antivirus/control-plane-container + - from: repo:infra-lxd + type: provides + to: capability:infra-lxd/container + - from: requirement:services-antivirus/control-plane-container + type: matches + to: capability:infra-lxd/container + - from: binding:infra-lxd/antivirus-control-plane + type: fulfills + to: requirement:services-antivirus/control-plane-container +``` + +Минимальные правила каталога: + +- обнаруживать `ops/contract.yaml` под настроенными roots; +- валидировать contract до индексации; +- требовать глобально уникальный `metadata.name`; +- хранить path и contract hash; +- строить relations из provides/requires/bindings; +- не копировать полный KDB в catalog; +- поддерживать полную пересборку без потери authoritative data. + +Рекомендуемые relation types первой версии: `owns`, `provides`, `requires`, `matches`, `fulfills`, `implements`, `documents`. Словарь relations MAY расширяться без изменения базового envelope. + +## 12. ContextBundle + +`ContextBundle` является детерминированным результатом выбора контекста. + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: ContextBundle +metadata: + name: infra-lxd-container-deploy +spec: + generatedAt: 2026-08-24T12:00:00Z + intent: container.deploy + repository: repo:infra-lxd + contractRevision: sha256:0123456789abcdef + summary: Managed LXD infrastructure + contentRoots: + - profiles-source + operations: + - operation:infra-lxd/container.inspect + - operation:infra-lxd/container.plan + topics: + - topic:infra-lxd/container-deployment + documents: + - canonical-lxd-reference + warnings: [] +``` + +ContextBundle MUST: + +- содержать только данные, выбранные для intent; +- иметь стабильную сортировку массивов; +- включать revision/hash источников; +- не содержать secrets; +- явно сообщать о truncation, stale или missing sources в `warnings`. + +## 13. Plan: зарезервированная L3-схема + +Plan описывает точный change set и не является командой. + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: Plan +metadata: + name: antivirus-container-20260824-001 +spec: + intent: container.deploy + createdAt: 2026-08-24T12:00:00Z + repositories: + - ref: repo:services-antivirus + revision: git:0123456789abcdef + - ref: repo:infra-lxd + revision: git:fedcba9876543210 + snapshots: + - ref: snapshot:lxd/20260824T115900Z + hash: sha256:0123456789abcdef + observedAt: 2026-08-24T11:59:00Z + steps: + - id: create-container + operation: operation:infra-lxd/container.apply + effect: external-write + risk: high + dependsOn: [] + verification: + - operation:infra-lxd/container.verify + rollback: + operation: operation:infra-lxd/container.rollback + approval: + required: true + planHash: sha256:0123456789abcdef +``` + +L3 implementation MUST: + +- вычислять `planHash` из canonical representation без поля `planHash`; +- перед apply повторно проверять revisions, snapshot freshness и preconditions; +- выполнять только операции и inputs из подтверждённого Plan; +- прекращать execution при провале checkpoint; +- не считать cross-repo workflow атомарной транзакцией. + +## 14. RunEvidence: зарезервированная L3-схема + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: RunEvidence +metadata: + name: antivirus-container-20260824-001 +spec: + runId: antivirus-container-20260824-001 + planRef: plan:antivirus-container-20260824-001 + planHash: sha256:0123456789abcdef + actor: user:example + startedAt: 2026-08-24T12:05:00Z + finishedAt: 2026-08-24T12:08:00Z + outcome: succeeded + steps: + - id: create-container + status: succeeded + providerVerification: passed + consumerAcceptance: passed + resultRef: lxd://drweb/dwcp + redactions: + - credentials +``` + +RunEvidence MUST NOT содержать secret values. Допустимые outcomes: `succeeded`, `failed`, `partial`, `cancelled`. + +## 15. Desired state, observed state и status + +| Понятие | Источник истины | Правило | +|---|---|---| +| Desired state | authored files в Git | описывает желаемое состояние | +| Observed state | runtime API/CLI | всегда имеет `observedAt` и provenance | +| Snapshot | immutable artifact | историческая фиксация observed state | +| Status | derived output | не редактируется как desired state | +| Condition | derived output | `type`, `status`, `reason`, `message`, `observedRevision`, `observedAt` | +| Drift | computed difference | не означает автоматический apply | + +Допустимые condition statuses: `True`, `False`, `Unknown`. + +Рекомендуемые condition types: + +```text +ContractValid +KnowledgeFresh +BindingsResolved +Ready +DriftDetected +VerificationSucceeded +AcceptanceSucceeded +``` + +## 16. Профили типов репозиториев + +### 16.1. Infrastructure configuration + +MUST разделять authored desired state и observed state. SHOULD предоставлять операции `inspect`, `validate`, `diff`, `plan`, `verify` до добавления `apply`. + +### 16.2. Service configuration + +MUST владеть product/service requirements и acceptance criteria. MUST NOT копировать provider-owned profiles, stacks, network configuration или inventory как свой authoritative state. + +### 16.3. Software + +SHOULD объявлять source, tests и build/package roots. Deployment artifacts MAY находиться в том же repo, но MUST иметь отдельный content root и authority. + +### 16.4. Project + +SHOULD объявлять deliverables, sources и decisions. MAY использовать datasets, working и archive roots. Не обязан иметь executable operations. + +## 17. Agent entrypoints и adapters + +### 17.1. `AGENTS.md` + +`AGENTS.md` MUST быть коротким и SHOULD содержать: + +1. назначение репозитория; +2. указание прочитать `ops/contract.yaml`; +3. указание получать знания через `repoctl context` или KDB topics; +4. обязательные safety constraints; +5. команды validation. + +`AGENTS.md` MUST NOT дублировать полный KDB, handlers или изменчивые live facts. + +### 17.2. `CLAUDE.md` + +При основном агенте Claude рекомендуемый минимальный файл: + +```markdown +@AGENTS.md + +## Claude-specific + +Use `repoctl context` before loading detailed knowledge or running repository operations. +``` + +### 17.3. Skills + +Skills MAY предоставлять UX для intents и workflows. Skills MUST вызывать канонический `repoctl`/handler и MUST NOT содержать вторую копию executable implementation. + +### 17.4. MCP + +MCP MAY публиковать те же данные позднее: + +- resources: contracts, selected KDB topics, ContextBundles, Plans, RunEvidence; +- tools: catalog search, describe, context, validate, plan, verify; +- write tools: только после L3 и domain-specific authorization. + +MCP является transport/discovery layer и MUST NOT становиться новым источником истины. + +## 18. Bootstrap, adoption и template update + +### 18.1. `repoctl init` + +MVP bootstrap SHOULD: + +1. определить repository type; +2. запросить `metadata.name`, title, owner и lifecycle; +3. создать `ops/contract.yaml`; +4. создать минимальный `kdb/kdb.yaml`; +5. создать `AGENTS.md` и `CLAUDE.md`; +6. предложить content roots, соответствующие type; +7. записать `spec.template.id`, version и revision; +8. выполнить `repoctl validate`; +9. показать точный diff до записи или commit. + +### 18.2. `repoctl adopt` + +`init` создаёт новый репозиторий, а `adopt` подключает существующий. Эти операции MUST NOT иметь одинаковую стратегию записи. + +`repoctl adopt` MUST работать по процедуре [adoption-runbook.md](adoption-runbook.md) и поддерживать этапы `assess`, `plan`, `apply` и `verify`. + +Стратегия по умолчанию — `overlay`. Стратегия `normalize` MAY использоваться только при явном `--strategy normalize`, с именованной recipe, полным rename/reference-rewrite plan и отдельным approval. Расширение `adopt` до normalization MUST NOT происходить по эвристике или только из-за необычного дерева. + +Adoption MUST: + +- сначала исследовать существующие authoritative paths, KDB, agent instructions, handlers и межрепозиторные ссылки; +- сохранять domain-native layout и объявлять его через `contentRoots`; +- не перемещать и не переписывать существующий KDB автоматически; +- создавать совместимый KDB index рядом, если канонический путь занят legacy-форматом; +- показывать полный diff до записи; +- разделять автоматически найденные факты и подтверждённые владельцем решения; +- допускать остановку после `assess` или `plan` без изменения репозитория; +- при `overlay` изменять только repository-local metadata после явного подтверждения; +- при `normalize` изменять только paths из подтверждённой recipe и обновлять все contract/KDB/Markdown references атомарно; +- завершаться `repoctl validate` и отчётом о неразрешённых findings. + +### 18.3. SSH и credentials + +Bootstrap MAY предложить создать отдельный SSH deploy key, но: + +- private key MUST NOT попадать в Git; +- public key MAY храниться только в явно предназначенном месте; +- доступ SHOULD быть read-only по умолчанию; +- key scope SHOULD быть ограничен одним repository; +- contract MAY хранить credential metadata/secret reference, но MUST NOT хранить значение секрета; +- для fleet-scale access SHOULD поддерживаться переход к app/short-lived credentials. + +### 18.4. Template migration + +Будущая команда `repoctl migrate` SHOULD: + +- сравнивать current template version с available version; +- использовать `template.revision` и несекретные answers; +- строить diff/plan до записи; +- не перезаписывать domain content roots; +- поддерживать versioned migrations. + +## 19. Команды MVP + +```text +repoctl init +repoctl adopt --repo PATH --mode assess|plan|apply|verify [--strategy overlay|normalize] [--recipe ID] +repoctl validate [--repo PATH] +repoctl discover --root PATH [--output yaml|json] +repoctl describe --repo NAME|PATH [--output yaml|json] +repoctl context --repo NAME|PATH --intent INTENT [--budget N] +``` + +### 19.1. Семантика + +| Команда | Writes | Результат | +|---|---|---| +| `init` | local, после review | skeleton и template lineage | +| `adopt --mode assess|plan` | none | inventory, findings, rename map и proposed diff | +| `adopt --mode apply` | local, после review | overlay metadata либо явно подтверждённая normalization recipe | +| `adopt --mode verify` | none | adoption report и compatibility level | +| `validate` | none | validation findings | +| `discover` | optional local cache | `CatalogIndex` | +| `describe` | none | normalized contract summary | +| `context` | none | `ContextBundle` | + +### 19.2. Exit codes + +| Code | Значение | +|---|---| +| `0` | success, no errors | +| `1` | validation or operation failure | +| `2` | invalid invocation/input | +| `3` | missing repository/resource | +| `4` | stale or incomplete context при strict mode | +| `5` | approval required или denied; reserved for L3 | + +### 19.3. Validation finding + +```yaml +severity: error +code: CONTRACT_PATH_OUTSIDE_REPOSITORY +resource: repo:infra-lxd +path: spec.contentRoots[0].path +message: Path resolves outside repository root +``` + +Severity MUST быть одной из `info`, `warning`, `error`. + +## 20. Validation rules MVP + +Validator MUST проверять: + +1. YAML parse и общий envelope; +2. apiVersion/kind; +3. ID formats и уникальность IDs внутри коллекций; +4. repository type и lifecycle enums; +5. безопасность и существование путей; +6. существование KDB entrypoint; +7. ссылки topics → documents; +8. ссылки relatedTopics; +9. freshness и provenance warnings; +10. отсутствие очевидных secret-shaped fields (`password`, `token`, `privateKey`, `secretValue`); +11. handler path и отсутствие shell string в operations; +12. уникальность repository names в CatalogIndex; +13. разрешимость local entity refs; +14. совместимость requirement capability с найденными providers как warning; +15. binding status/evidence consistency как warning. + +## 21. Security invariants + +Любая реализация MUST соблюдать: + +- read-only по умолчанию; +- fail closed при неизвестном effect, risk или apiVersion; +- отсутствие shell interpolation; +- path confinement к repo root; +- отсутствие secrets в outputs; +- redaction до записи evidence; +- отдельные domain credentials; +- plan и approval до write-операций L3; +- immutable revisions для cross-repo Plan; +- allowlisted handlers; +- consumer-owned acceptance и provider-owned verification. + +## 22. Versioning и расширения + +### 22.1. Alpha compatibility + +В `v1alpha1` breaking changes допускаются только с изменением `apiVersion` или `documentVersion` и migration note. + +### 22.2. Неизвестные поля + +- Validator SHOULD отклонять неизвестные поля в нормативных объектах. +- Поля с префиксом `x-` MAY использоваться для экспериментальных расширений. +- `metadata.annotations` MAY содержать tool-specific metadata. +- Consumer MUST сохранять неизвестные `x-*` поля при read-modify-write. + +### 22.3. Открытые словари + +Следующие значения намеренно открыты для расширения: + +- content root `role`; +- capability name; +- intent ID; +- precondition ID; +- condition type; +- domain-specific binding target URI. + +Закрытые enums первой версии: + +- repository type; +- lifecycle; +- access; +- content authority/writePolicy/kind; +- operation phase/effect/risk; +- knowledge authority/status/role; +- binding status; +- evidence outcome. + +## 23. Порядок реализации + +### Phase A: schema and parser + +1. Реализовать модели envelope, RepositoryContract и KnowledgeBase. +2. Реализовать YAML loader без исполнения кода. +3. Реализовать path confinement и validation findings. +4. Добавить contract/KDB fixtures для четырёх repository types. + +### Phase B: read-only repoctl + +1. `validate`. +2. `discover` и `CatalogIndex`. +3. `describe`. +4. `context` и `ContextBundle`. +5. JSON и YAML output со стабильной сортировкой. + +### Phase C: bootstrap and adoption + +1. `init` для четырёх repository types. +2. `adopt` для существующих layouts без перемещения domain content. +3. Генерация или бережная адаптация Claude/AGENTS entrypoints. +4. Legacy KDB compatibility index. +5. Именованные normalization recipes; первая — `documents-to-content-root`. +6. Template lineage. +7. Preview/diff до записи. + +### Phase D: pilots + +1. Infrastructure pilot: `Infra/LXD`. +2. Service pilot: `Services/Antivirus`. +3. Cross-repo requirement/capability discovery. +4. Intent `container.deploy` без apply. + +### Phase E: operations + +1. Зафиксировать L2 handler ABI. +2. Добавить inspect/validate/diff/plan/verify. +3. Зафиксировать Plan hashing и approval. +4. Только затем добавить scoped apply и MCP adapters. + +## 24. Acceptance criteria MVP + +MVP считается готовым, когда: + +1. четыре fixtures представляют четыре repository types; +2. `repoctl validate` выдаёт одинаковые findings для YAML и JSON output; +3. `repoctl discover` находит contracts и строит воспроизводимый CatalogIndex; +4. duplicate repository ID является error; +5. `repoctl describe` не читает весь KDB; +6. `repoctl context --intent container.deploy` выбирает только связанные topics/documents/operations; +7. stale source явно попадает в warnings; +8. path traversal блокируется; +9. secret-shaped value блокируется или redacts согласно типу ресурса; +10. LXD content roots обнаруживаются без перемещения profiles; +11. Antivirus requirement разрешается к LXD capability; +12. никакая MVP-команда не изменяет external system; +13. `CLAUDE.md` остаётся коротким и использует portable instructions; +14. CatalogIndex полностью пересоздаётся из repo-local contracts; +15. добавление новой content role не требует изменения базового parser. +16. `adopt --mode plan` не изменяет рабочее дерево и выдаёт детерминированный proposed diff; +17. adoption LXD сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml` на месте; +18. adoption Antivirus не перезаписывает существующий custom `kdb/kdb.yaml`. +19. `documents-to-content-root` не перемещает `README.md`, `AGENTS.md`, `CLAUDE.md`, license и community files; +20. normalization plan включает rename map и обновляет contract, KDB, frontmatter и Markdown links до записи. + +## 25. Сквозной пример contract: infrastructure provider + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: RepositoryContract +metadata: + name: infra-lxd + title: LXD infrastructure + owners: + - infrastructure + labels: + domain: compute +spec: + summary: Desired state and operations for managed LXD containers + repository: + type: infrastructure-config + lifecycle: production + namespace: Infra + access: restricted + template: + id: repository.infrastructure + version: 0.1.0 + source: repo:repository-templates + agent: + primary: CLAUDE.md + portable: AGENTS.md + knowledge: + entrypoint: kdb/kdb.yaml + contentRoots: + - id: profiles-source + role: profiles + path: profiles-source + kind: directory + authority: source + writePolicy: managed + selector: "**/*.yaml" + - id: profiles-observed + role: observed + path: profiles + kind: directory + authority: mirror + writePolicy: generated + selector: "**/*.yaml" + provides: + - id: container + capability: compute.lxd-container + summary: Managed LXD system container + bindings: + - id: antivirus-control-plane + requirement: requirement:services-antivirus/control-plane-container + target: lxd://drweb/dwcp + status: active + evidenceRef: run-evidence://antivirus-control-plane/latest + operations: + - id: container.inspect + title: Inspect containers + intents: + - container.inspect + - container.deploy + phase: inspect + effect: read-only + risk: low + execution: + handler: ops/handlers/lxd.py + argv: + - inspect + preconditions: + - contract.valid + - id: container.plan + title: Plan container changes + intents: + - container.deploy + phase: plan + effect: local-write + risk: medium + execution: + handler: ops/handlers/lxd.py + argv: + - plan + preconditions: + - contract.valid + - knowledge.fresh +``` + +## 26. Сквозной пример contract: service consumer + +```yaml +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: RepositoryContract +metadata: + name: services-antivirus + title: Antivirus service + owners: + - security +spec: + summary: Product configuration, knowledge and acceptance for antivirus services + repository: + type: service-config + lifecycle: production + namespace: Services + access: restricted + template: + id: repository.service + version: 0.1.0 + source: repo:repository-templates + agent: + primary: CLAUDE.md + portable: AGENTS.md + knowledge: + entrypoint: kdb/kdb.yaml + contentRoots: + - id: product-policies + role: policies + path: policies + kind: directory + authority: source + writePolicy: managed + - id: service-acceptance + role: acceptance + path: acceptance + kind: directory + authority: source + writePolicy: managed + requires: + - id: control-plane-container + capability: compute.lxd-container + summary: Container for antivirus control plane + constraints: + cpu: 4 + memory: 8GiB + networkZone: services + acceptance: + - operation:services-antivirus/control-plane.verify + operations: + - id: control-plane.verify + title: Verify antivirus control plane + intents: + - container.deploy + - service.verify + phase: verify + effect: read-only + risk: low + execution: + handler: ops/handlers/antivirus.py + argv: + - verify-control-plane + preconditions: + - binding.active +``` + +## 27. Принципиальные инварианты модели + +```yaml +invariants: + authority: + catalogIsDerived: true + contractIsRepositoryLocal: true + desiredIsNotObserved: true + snapshotIsNotDesired: true + ownership: + consumerOwnsRequirements: true + consumerOwnsAcceptance: true + providerOwnsCapabilities: true + providerOwnsBindings: true + providerOwnsVerification: true + execution: + arbitraryShellForbidden: true + handlersHaveSingleCanonicalCopy: true + writeRequiresPlanAndApprovalAtL3: true + knowledge: + kdbIsIndexAndRouter: true + contextIsSelectedByIntent: true + provenanceRequiredForVolatileFacts: true + secretsForbidden: true + portability: + contractIsHarnessNeutral: true + skillsAreAdapters: true + mcpIsOptionalTransport: true +``` + +## 28. Design lineage + +Следующая машиночитаемая карта фиксирует происхождение ключевых решений. Внешние форматы не являются runtime dependencies протокола. + +```yaml +designLineage: + repositoryDescriptor: + adopted: + - repo-local-source-of-truth + - derived-catalog + - versioned-kind-envelope + sources: + - https://backstage.io/docs/features/software-catalog/ + - https://backstage.io/docs/features/software-catalog/descriptor-format/ + scaffolding: + adopted: + - typed-inputs + - preview-before-write + - template-lineage + - versioned-migrations + sources: + - https://backstage.io/docs/features/software-templates/ + - https://copier.readthedocs.io/en/stable/updating/ + desiredAndObservedState: + adopted: + - declarative-desired-state + - reconciliation + - spec-status-separation + - conditions-and-observed-revision + sources: + - https://opengitops.dev/ + - https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api-conventions.md + consumerProviderBoundary: + adopted: + - consumer-owned-requirements + - provider-owned-implementation + - platform-neutral-capabilities + sources: + - https://docs.crossplane.io/latest/composition/composite-resources/ + - https://docs.score.dev/docs/ + operationDescription: + adopted: + - stable-operation-id + - input-output-schema + - workflow-dependencies + - success-criteria + sources: + - https://spec.openapis.org/oas/latest.html + - https://spec.openapis.org/arazzo/latest.html + agentInteroperability: + adopted: + - concise-agent-entrypoint + - on-demand-context + - thin-skills + - optional-resources-tools-transport + sources: + - https://code.claude.com/docs/en/memory + - https://agents.md/ + - https://modelcontextprotocol.io/specification/2025-06-18/server/index + knowledgeAndProvenance: + adopted: + - machine-human-index + - topic-routing + - provenance + - freshness + - docs-as-code + sources: + - https://specs.frictionlessdata.io/guides/data-package/ + - https://www.w3.org/TR/prov-o/ + - https://diataxis.fr/ + - https://backstage.io/docs/features/techdocs/ + repositorySafety: + adopted: + - ownership + - review-and-protection + - least-privilege + - provenance-and-integrity + sources: + - https://github.com/ossf/scorecard/blob/main/docs/checks.md + - https://slsa.dev/spec/v1.2/provenance + - https://spdx.github.io/spdx-spec/v3.0.1/scope/ +``` diff --git a/kdb/kdb.yaml b/kdb/kdb.yaml new file mode 100644 index 0000000..f4c6ac3 --- /dev/null +++ b/kdb/kdb.yaml @@ -0,0 +1,186 @@ +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: KnowledgeBase +metadata: + name: repository-stewardship-kdb + title: Repository Stewardship knowledge index +spec: + repository: repo:repository-stewardship + defaultLanguage: ru + topics: + - id: repository-bootstrap + title: Bootstrap a new repository + summary: Choose a repository type and create the minimal Stewardship layer without inventing domain content + intents: + - repository.initialize + - repository.bootstrap + keywords: + - init + - template + - ssh + - contract + priority: 90 + documents: + - stewardship-specification + - stewardship-guide + data: + loadPolicy: headings-only + readHints: + - document: stewardship-specification + headings: + - 1. Цели и границы + - 3. Каноническое обнаружение + - 5. RepositoryContract + - 6. ContentRoot + - 17. Agent entrypoints и adapters + - 18. Bootstrap, adoption и template update + - document: stewardship-guide + headings: + - 4. Минимальная структура репозитория + - 5. Четыре типа репозиториев + - 17. Bootstrap нового и adoption существующего репозитория + - id: repository-adoption + title: Adopt an existing repository + summary: Assess, plan and apply a metadata overlay while preserving existing authoritative content + intents: + - repository.adopt + - repository.standardize + - repository.normalize + keywords: + - assess + - overlay + - legacy + - migration + priority: 100 + documents: + - adoption-runbook + - stewardship-specification + data: + loadPolicy: runbook-first + phases: + - assess + - plan + - review + - apply + - verify + readHints: + - document: adoption-runbook + headings: + - 3. Safety invariants + - 6. Phase 1 — preflight + - 7. Phase 2 — assessment + - 10. Phase 4 — adoption plan + - 11. Compatibility rules + - 11.5. Normalization recipe documents-to-content-root + - 12. Phase 5 — apply + - 13. Phase 6 — verify + - id: stewardship-model + title: Understand or evolve the model + summary: Definitions, invariants, schemas and the reasoning behind Repository Stewardship + intents: + - repository.model.explain + - repository.model.change + - repository.standard.design + keywords: + - contract + - intent + - capability + - requirement + - binding + - kdb + priority: 80 + documents: + - stewardship-specification + - stewardship-guide + - architecture-options + data: + loadPolicy: specification-first + authorityOrder: + - stewardship-specification + - stewardship-guide + - architecture-options + - id: tooling-implementation + title: Implement repoctl or an adapter + summary: Implementation boundary, commands, validation rules and harness-neutral adapter design + intents: + - repository.tooling.implement + - repository.tooling.test + - repository.adapter.create + keywords: + - repoctl + - parser + - schema + - validator + - skill + - mcp + priority: 85 + documents: + - stewardship-specification + - adoption-runbook + - stewardship-guide + data: + loadPolicy: selected-sections + readHints: + - document: stewardship-specification + headings: + - 19. Команды MVP + - 20. Validation rules MVP + - 21. Security invariants + - 22. Versioning и расширения + - 23. Порядок реализации + - 24. Acceptance criteria MVP + - document: stewardship-guide + headings: + - 14. Интерфейсы для агентов и людей + - 15. Простая первая версия + - 16. Предлагаемая внутренняя структура repoctl + - id: architecture-research + title: Revisit architecture choices + summary: Earlier alternatives, trade-offs and external design lineage + intents: + - repository.architecture.research + - repository.architecture.compare + keywords: + - architecture + - alternatives + - backstage + - gitops + - mcp + priority: 50 + documents: + - architecture-options + - stewardship-specification + data: + loadPolicy: research-on-demand + readHints: + - document: stewardship-specification + headings: + - 28. Design lineage + documents: + - id: stewardship-specification + title: Repository Stewardship Protocol + role: reference + path: docs/specification.md + mediaType: text/markdown + authority: local-canonical + status: draft + - id: stewardship-guide + title: Repository Stewardship human guide + role: explanation + path: docs/guide.md + mediaType: text/markdown + authority: local-canonical + status: draft + - id: adoption-runbook + title: Repository Adoption Runbook + role: runbook + path: docs/adoption-runbook.md + mediaType: text/markdown + authority: local-canonical + status: draft + - id: architecture-options + title: Infrastructure operations architecture options + role: explanation + path: docs/research/infrastructure-operations-architecture-options.md + mediaType: text/markdown + authority: manual + status: draft diff --git a/ops/contract.yaml b/ops/contract.yaml new file mode 100644 index 0000000..da47b54 --- /dev/null +++ b/ops/contract.yaml @@ -0,0 +1,47 @@ +apiVersion: stewardship.corsus.ru/v1alpha1 +kind: RepositoryContract +metadata: + name: repository-stewardship + title: Repository Stewardship standards and templates + owners: + - alexander.baranov + labels: + domain: repository-management + role: standards-and-templates + annotations: + stewardship.corsus.ru/bootstrap-mode: self-hosted + stewardship.corsus.ru/implementation-status: specification-only +spec: + summary: Standards, templates and adoption guidance for AI-assisted repository management + repository: + type: project + lifecycle: active + agent: + primary: CLAUDE.md + portable: AGENTS.md + knowledge: + entrypoint: kdb/kdb.yaml + contentRoots: + - id: canonical-documents + role: documentation + path: docs + kind: file-set + authority: source + writePolicy: managed + selector: "*.md" + format: text/markdown + - id: architecture-research + role: design-source + path: docs/research + kind: file-set + authority: source + writePolicy: managed + selector: "**/*.md" + format: text/markdown + provides: + - id: stewardship-model + capability: repository.stewardship-model + summary: Versioned contract and knowledge model for managed repositories + - id: adoption-procedure + capability: repository.adoption-procedure + summary: Safe overlay procedure for bringing existing repositories into the model