54 KiB
documentId, documentVersion, schemaApiVersion, status, normative, language, companionDocument, architectureSource
| documentId | documentVersion | schemaApiVersion | status | normative | language | companionDocument | architectureSource |
|---|---|---|---|---|---|---|---|
| repository-stewardship-protocol | 0.2.0 | stewardship.corsus.ru/v1alpha1 | draft | true | ru | docs/guide.md | 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. Процедура подключения существующих репозиториев находится в adoption-runbook.md. Исходное архитектурное исследование находится в research/infrastructure-operations-architecture-options.md.
1. Цели и границы
1.1. Цели
Протокол MUST обеспечивать:
- единую точку обнаружения репозитория;
- определение типа, назначения и владельца репозитория;
- обнаружение штатных мест результата работы через
contentRoots; - выборочную загрузку знаний по
intent; - декларацию capabilities, requirements и bindings;
- обнаружение разрешённых операций без копирования handlers в skills;
- построение производного каталога и графа отношений;
- независимость от LLM, agent harness, транспорта и языка handlers;
- последующее добавление 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-ресурсы протокола используют общий верхний уровень:
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 соответствовать выражению:
^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$
Рекомендуемый формат — domain.action или domain.object, например:
container.deploy
container.inspect
knowledge.lookup
repository.initialize
4.4. Ссылки на сущности
Cross-repository ссылки используют следующие формы:
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>
Примеры:
repo:infra-lxd
capability:infra-lxd/container
requirement:services-antivirus/control-plane-container
operation:services-antivirus/control-plane.verify
5. RepositoryContract
5.1. Минимальный валидный contract
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
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
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
agent:
primary: CLAUDE.md
portable: AGENTS.md
primary SHOULD быть CLAUDE.md, пока основным агентом является Claude. portable SHOULD быть AGENTS.md.
5.6. knowledge
knowledge:
entrypoint: kdb/kdb.yaml
Если knowledge.entrypoint объявлен, файл MUST существовать и содержать kind: KnowledgeBase, кроме репозитория с lifecycle: stub.
6. ContentRoot
6.1. Формат
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.
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.
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.
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:
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. Формат
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
Допустимые значения:
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.handlerMUST быть repo-relative path;execution.argvMUST быть массивом статических токенов;- contract MUST NOT содержать shell pipelines, redirections или command substitution;
repoctlMUST запускать handler без shell interpolation;- dynamic input MUST передаваться структурированно после schema validation;
- effect
external-write,disruptiveиdestructiveMUST требовать plan и approval на уровнеL3.
Точный общий handler ABI откладывается до L2. До его утверждения adapters MAY вызывать существующие handlers через repo-specific implementation, но публичная семантика operation ID MUST оставаться стабильной.
10. KnowledgeBase
10.1. Минимальный KDB
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
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
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:
tutorial
how-to
reference
explanation
runbook
vendor-source
evidence
Допустимые authority:
vendor
local-canonical
observed
derived
manual
Допустимые status:
verified
manual
draft
stale
10.5. Provenance rules
provenance.sha256, если указан, MUST быть lowercase SHA-256 из 64 hex symbols.status: verifiedSHOULD иметьfreshness.verifiedAt.- Если
freshness.expiresAt <= currentTime, consumer MUST считать документ stale независимо от authoredstatusи 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:
- загрузить и валидировать contract;
- загрузить KDB по
knowledge.entrypoint; - выбрать topics, где
topic.intentsсодержит точное значение intent; - отсортировать topics по
priority DESC, затемid ASC; - включить
topic.dataи ссылки на documents; - убрать повторяющиеся documents по ID;
- пометить отсутствующие и stale documents warnings;
- включить operations, где
operation.intentsсодержит intent; - включить относящиеся к repo
contentRoots; - не загружать
relatedTopicsбез явного--include-related; - соблюдать заданный byte/token budget детерминированным образом.
Keyword search MAY дополнять exact intent routing, но MUST NOT вытеснять его в MVP.
11. CatalogIndex
CatalogIndex является полностью производным ресурсом и MUST NOT редактироваться вручную.
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 является детерминированным результатом выбора контекста.
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 и не является командой.
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-схема
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:
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 содержать:
- назначение репозитория;
- указание прочитать
ops/contract.yaml; - указание получать знания через
repoctl contextили KDB topics; - обязательные safety constraints;
- команды validation.
AGENTS.md MUST NOT дублировать полный KDB, handlers или изменчивые live facts.
17.2. CLAUDE.md
При основном агенте Claude рекомендуемый минимальный файл:
@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:
- определить repository type;
- запросить
metadata.name, title, owner и lifecycle; - создать
ops/contract.yaml; - создать минимальный
kdb/kdb.yaml; - создать
AGENTS.mdиCLAUDE.md; - предложить content roots, соответствующие type;
- записать
spec.template.id, version и revision; - выполнить
repoctl validate; - показать точный diff до записи или commit.
18.2. repoctl adopt
init создаёт новый репозиторий, а adopt подключает существующий. Эти операции MUST NOT иметь одинаковую стратегию записи.
repoctl adopt MUST работать по процедуре 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
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 |
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
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 проверять:
- YAML parse и общий envelope;
- apiVersion/kind;
- ID formats и уникальность IDs внутри коллекций;
- repository type и lifecycle enums;
- безопасность и существование путей;
- существование KDB entrypoint;
- ссылки topics → documents;
- ссылки relatedTopics;
- freshness и provenance warnings;
- отсутствие очевидных secret-shaped fields (
password,token,privateKey,secretValue); - handler path и отсутствие shell string в operations;
- уникальность repository names в CatalogIndex;
- разрешимость local entity refs;
- совместимость requirement capability с найденными providers как warning;
- 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.annotationsMAY содержать 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
- Реализовать модели envelope, RepositoryContract и KnowledgeBase.
- Реализовать YAML loader без исполнения кода.
- Реализовать path confinement и validation findings.
- Добавить contract/KDB fixtures для четырёх repository types.
Phase B: read-only repoctl
validate.discoverиCatalogIndex.describe.contextиContextBundle.- JSON и YAML output со стабильной сортировкой.
Phase C: bootstrap and adoption
initдля четырёх repository types.adoptдля существующих layouts без перемещения domain content.- Генерация или бережная адаптация Claude/AGENTS entrypoints.
- Legacy KDB compatibility index.
- Именованные normalization recipes; первая —
documents-to-content-root. - Template lineage.
- Preview/diff до записи.
Phase D: pilots
- Infrastructure pilot:
Infra/LXD. - Service pilot:
Services/Antivirus. - Cross-repo requirement/capability discovery.
- Intent
container.deployбез apply.
Phase E: operations
- Зафиксировать L2 handler ABI.
- Добавить inspect/validate/diff/plan/verify.
- Зафиксировать Plan hashing и approval.
- Только затем добавить scoped apply и MCP adapters.
24. Acceptance criteria MVP
MVP считается готовым, когда:
- четыре fixtures представляют четыре repository types;
repoctl validateвыдаёт одинаковые findings для YAML и JSON output;repoctl discoverнаходит contracts и строит воспроизводимый CatalogIndex;- duplicate repository ID является error;
repoctl describeне читает весь KDB;repoctl context --intent container.deployвыбирает только связанные topics/documents/operations;- stale source явно попадает в warnings;
- path traversal блокируется;
- secret-shaped value блокируется или redacts согласно типу ресурса;
- LXD content roots обнаруживаются без перемещения profiles;
- Antivirus requirement разрешается к LXD capability;
- никакая MVP-команда не изменяет external system;
CLAUDE.mdостаётся коротким и использует portable instructions;- CatalogIndex полностью пересоздаётся из repo-local contracts;
- добавление новой content role не требует изменения базового parser.
adopt --mode planне изменяет рабочее дерево и выдаёт детерминированный proposed diff;- adoption LXD сохраняет
profiles-source/,profiles/и rootkdb.yamlна месте; - adoption Antivirus не перезаписывает существующий custom
kdb/kdb.yaml. documents-to-content-rootне перемещаетREADME.md,AGENTS.md,CLAUDE.md, license и community files;- normalization plan включает rename map и обновляет contract, KDB, frontmatter и Markdown links до записи.
25. Сквозной пример contract: infrastructure provider
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
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. Принципиальные инварианты модели
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 протокола.
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/