--- 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/ ```