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>
1437 lines
56 KiB
Markdown
1437 lines
56 KiB
Markdown
---
|
||
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/
|
||
```
|