Files
repoctl/docs/specification.md
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

56 KiB
Raw Permalink Blame History

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 обеспечивать:

  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-ресурсы протокола используют общий верхний уровень:

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.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

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: 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 редактироваться вручную.

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 содержать:

  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 рекомендуемый минимальный файл:

@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 и поддерживать этапы 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

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 проверять:

  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

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/