Files
repoctl/docs/specification.md
T
Alexander BaranovandClaude Opus 5 1ab02a257c fix(adopt,init): decide by evidence, refuse instead of defaulting
Running a full assess -> plan -> apply -> verify against Infra/LXD and
Infra/Docker in throwaway worktrees, and a bootstrap into a scratch
directory, surfaced the same two mistakes repeated across both commands:
a shape was read where evidence was available, and a missing answer became
a silent default rather than a refusal.

adopt:

- classify secret-shaped paths by content, not by filename. A live
  credential blocks; a file tracked against the repository's own ignore
  rules and a name-only match are warnings; findings name keys, never
  values. In Infra/Docker this turned 14 false blockers into 2 true ones
  and surfaced 14 files committed despite `**/.env`.
- carry assess findings into the plan and refuse while an error-severity
  finding is unresolved. An owner may accept one through
  `acknowledgedFindings` with a reason; the acknowledgement enters the
  plan and therefore planHash, so approval covers it.
- derive metadata.name from the git remote instead of the clone directory,
  and refuse to plan without a confirmed owner (runbook section 9).
- propose content roots from the whole content vocabulary rather than the
  winning type's markers, and recognise N sibling directories sharing a
  marker file as one file-set root with a selector, as runbook 7.2 already
  specified. Authority defaulted rather than derived now asks.

init: apply the guards adopt already had. Answers are validated against
the vocabularies that already existed in constants (name, type, lifecycle,
access) so init can no longer create a repository that fails its own
validate; owners are required; a directory that already holds the planned
paths is refused at plan time and pointed at adopt; and every path from a
plan is confined before the first byte is written -- init wrote outside
the repository from an edited plan.

validate: mask fenced blocks and inline code spans before scanning for
Markdown links. A PowerShell snippet in Infra/Docker's CLAUDE.md parsed as
a link and kept validate red for a reason unrelated to the repository.

paths: allow "." as a whole content-root path, never as a segment, so the
file-set root runbook 7.2 describes can be declared.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 18:10:59 +03:00

1437 lines
56 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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:<repository-name>
capability:<repository-name>/<capability-id>
requirement:<repository-name>/<requirement-id>
binding:<repository-name>/<binding-id>
operation:<repository-name>/<operation-id>
topic:<repository-name>/<topic-id>
```
Примеры:
```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 <intent> --repo <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`
`init` — единственный путь, где инструмент контролирует каждый байт результата, поэтому созданный им репозиторий MUST проходить `repoctl validate` по построению. Ответы MUST проверяться до сборки плана: `metadata.name` против `ID_PATTERN`, type против набора типов, lifecycle и access против своих enum. Owner MUST быть подтверждён — та же граница, что и в `adopt`: контракт не знает, какая команда его создала.
`init` MUST отказываться планировать в каталог, где уже лежит любой из создаваемых им путей, и указывать на `adopt` как на правильную операцию. `apply` MUST confine каждый путь из плана внутрь репозитория: план — обычный файл, который можно отредактировать вручную.
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 до записи;
- разделять автоматически найденные факты и подтверждённые владельцем решения;
- отказываться строить plan без подтверждённого owner и выводить `metadata.name` из remote, а не из имени каталога клона;
- переносить findings из assessment в plan и отказываться строить plan, пока остаётся неразрешённая находка severity `error`; принятие такой находки MUST быть явным, с указанием причины, и входить в `planHash`;
- классифицировать secret-shaped пути по содержимому, а не только по имени, и не выводить значения — только имена ключей;
- допускать остановку после `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 до записи;
21. `adopt --mode plan` отказывается строиться без подтверждённого owner и при неразрешённой находке severity `error`;
22. содержимое secret-shaped файла может читаться для классификации, но значения не попадают ни в один вывод;
23. content roots предлагаются по всему словарю содержимого, а не только по маркерам предложенного type;
24. репозиторий из однотипных каталогов объявляется одним `file-set` корнем с селектором, а не N директориями.
## 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/
```