docs: baseline specification-only repository stewardship

This commit is contained in:
Alexander Baranov
2026-08-24 14:39:09 +03:00
commit 9a39b8a941
11 changed files with 4191 additions and 0 deletions
+660
View File
@@ -0,0 +1,660 @@
---
documentId: repository-adoption-runbook
documentVersion: 0.1.0
protocol: Repository Stewardship
schemaApiVersion: stewardship.corsus.ru/v1alpha1
status: proposed
normative: false
language: ru
machineSpecification: docs/specification.md
humanGuide: docs/guide.md
defaultStrategy: overlay
primaryAgent: Claude
portable: true
---
# Repository Adoption Runbook
## 0. Назначение и решение
Этот runbook подключает существующий Git-репозиторий к Repository Stewardship без перестройки его полезного содержимого.
Рекомендованная реализация состоит из двух слоёв:
1. этот runbook — переносимый источник истины для человека и любого агента;
2. тонкий skill `repository-adoption` — удобный Claude-интерфейс, который следует runbook и позднее вызывает `repoctl adopt`.
Skill не должен содержать отдельную логику классификации, генерации или проверки. Иначе Claude и другие агенты начнут переводить репозитории по разным правилам.
## 1. Термины
| Термин | Значение |
|---|---|
| `init` | создание нового репозитория из шаблона |
| `adopt` | первое подключение существующего репозитория к стандарту |
| `migrate` | обновление уже подключённого репозитория между версиями schema/template |
| `overlay` | добавляем stewardship metadata, не перемещая domain content |
| `normalize` | отдельно согласованное перемещение или переименование существующих файлов |
| `assessment` | только факты и выводы, полученные без записи |
| `adoption plan` | точный предлагаемый набор repository-local изменений |
`adopt` MUST NOT неявно превращаться в `normalize` или `migrate`.
## 2. Почему стратегия overlay используется по умолчанию
В обследованных `Infra` и `Services` встречаются разные, но уже осмысленные структуры:
- `Infra/LXD`: `profiles-source/` является source of truth, `profiles/` — mirror, KDB находится в корне, а существующие skills уже управляют профилями;
- `Infra/Docker`: stack directories находятся непосредственно в корне и не должны быть перенесены в общий `payload/`;
- `Infra/Network`: собственные зоны `shared/`, `clients/`, `egress/`, `wan/`, `wifi/`;
- `Services/Antivirus`: большой custom `kdb/kdb.yaml`, vendor sources, policies и ссылки на authoritative artifacts в LXD/Network/Docker;
- `Services/Monitoring` и `Services/Surveillance`: уже имеют KDB и domain-specific tools, но не одинаковые agent entrypoints.
Общий интерфейс здесь полезнее общего физического дерева. Adoption объявляет существующие места через contract и compatibility index.
```mermaid
flowchart LR
LEGACY["Существующий layout"] --> OVERLAY["Stewardship overlay"]
OVERLAY --> CONTRACT["ops/contract.yaml"]
OVERLAY --> KNOWLEDGE["KnowledgeBase index or adapter"]
OVERLAY --> ENTRY["CLAUDE.md + AGENTS.md pointers"]
CONTRACT --> ROOTS["Existing contentRoots stay in place"]
KNOWLEDGE --> SOURCES["Existing KDB and vendor sources stay in place"]
```
## 3. Safety invariants
Во время adoption агент или инструмент MUST:
- выполнять `assess` и `plan` только на чтение;
- не читать и не выводить содержимое private keys, tokens, passwords, `.env` и secret stores;
- не выполнять обнаруженные scripts, hooks, skills или operations;
- не подключаться к серверам и не изменять external systems;
- не перемещать, не удалять и не переименовывать существующие файлы;
- не переписывать существующие KDB и agent instructions целиком;
- не менять Git remote, default branch, history, permissions или access scope;
- не коммитить и не отправлять изменения без отдельного запроса;
- показать proposed diff до `apply`;
- остановить `apply`, если baseline revision изменился после `plan`;
- сохранять неизвестные `x-*` поля и существующие пользовательские секции.
Dirty working tree не мешает `assess`, но MUST быть явно отмечен. Для `apply` SHOULD использоваться чистая отдельная ветка либо подтверждённый набор непересекающихся paths.
## 4. Режимы adoption
```yaml
adoptionModes:
assess:
writes: false
output: AdoptionAssessment
plan:
writes: false
output: AdoptionPlan
apply:
writes: repository-local
approvalRequired: true
allowedScope: proposedPathsOnly
verify:
writes: false
output: AdoptionReport
```
До реализации CLI эти режимы являются логическими этапами runbook. После реализации им соответствуют:
```text
repoctl adopt --repo PATH --mode assess --output yaml
repoctl adopt --repo PATH --mode plan --output yaml
repoctl adopt --repo PATH --mode apply --plan PLAN --approve PLAN_HASH
repoctl adopt --repo PATH --mode verify --output yaml
```
## 5. Входные данные
Минимально необходимы:
- локальный путь или repository URL;
- read access;
- ожидаемый owner, если он уже известен;
- scope: один repository или явно перечисленная rollout wave.
Полезны, но не обязательны:
- предполагаемый repository type;
- ссылка на Git hosting project;
- известные связанные repositories;
- выбранный template version;
- сведения о protected branch/CODEOWNERS.
Отсутствующие сведения становятся questions, а не догадками, записанными как fact.
## 6. Phase 1 — preflight
### 6.1. Найти границу репозитория
Определить ближайший корень с `.git`. Nested repositories оцениваются отдельно. Каталог, содержащий несколько repositories, не получает один общий contract вместо них.
### 6.2. Зафиксировать Git baseline
Собрать без изменения состояния:
- current branch;
- HEAD revision;
- наличие staged, modified и untracked paths;
- remotes без credentials;
- tracked/untracked status будущих stewardship paths.
Не включать содержимое diff в централизованный отчёт без необходимости: для планирования достаточно списка paths и локального review.
### 6.3. Проверить collisions
Проверить существование:
```text
ops/contract.yaml
kdb/kdb.yaml
kdb.yaml
CLAUDE.md
AGENTS.md
.claude/skills/
.agents/skills/
ops/handlers/
ops/template-answers.yaml
```
Существующий path никогда не считается свободным только потому, что его формат неизвестен.
## 7. Phase 2 — assessment
### 7.1. Определить repository type
Тип выбирается по основному результату работы, а не по имени родительского каталога.
| Основной результат | Type |
|---|---|
| desired infrastructure state, inventory, profiles, networks, stacks | `infrastructure-config` |
| конфигурация и эксплуатационная модель конкретного сервиса | `service-config` |
| компилируемый/исполняемый код, library или application | `software` |
| документы, решения, datasets и deliverables проекта | `project` |
Если evidence указывает на два типа, выбрать владельца основного результата, а второй аспект отразить labels/content roots. Не создавать новый type только из-за смешанного layout.
### 7.2. Найти authoritative content
Для каждого значимого path определить:
- role;
- `source`, `generated`, `observed`, `mirror` или `evidence`;
- write policy;
- selector;
- кто реально владеет изменением.
Примеры:
```yaml
contentRoots:
- id: lxd-profile-sources
role: profiles
path: profiles-source
kind: file-set
authority: source
writePolicy: managed
selector: "*.yaml"
- id: lxd-live-profile-mirror
role: observed
path: profiles
kind: file-set
authority: mirror
writePolicy: generated
selector: "*.yaml"
- id: docker-stacks
role: stacks
path: .
kind: file-set
authority: source
writePolicy: managed
selector: "*/compose.y*ml"
```
Нельзя объявлять mirror как source только потому, что его YAML выглядит полнее.
### 7.3. Найти знания и provenance
Для каждого KDB/document source записать:
- path или URI;
- фактический формат;
- размер и верхнеуровневую структуру без загрузки всего содержимого в agent context;
- наличие index/routing;
- authority и status;
- vendor/local/observed provenance;
- freshness signals;
- наличие потенциальных secret-shaped paths или keys без вывода values.
### 7.4. Найти agent entrypoints и automation
Определить:
- какой файл сейчас является фактическим источником инструкций;
- есть ли противоречия или циклические ссылки между `CLAUDE.md` и `AGENTS.md`;
- какие skills/handlers каноничны;
- какие команды являются read-only, а какие меняют local/external state;
- где описан verify.
Наличие Claude-specific skill не делает его переносимым handler. В contract сначала регистрируется семантика операции, а адаптация skill выполняется позднее на L2.
### 7.5. Найти cross-repository relations
Записывать отношения по authority, а не по случайным относительным путям:
- service requirement → infrastructure capability;
- local pointer → authoritative artifact in provider repository;
- generated mirror → source root;
- runbook → operation/handler;
- vendor source → derived local knowledge.
## 8. Машиночитаемый результат assessment
До появления стабильного protocol kind используется versioned runbook output. Он не коммитится в целевой repository по умолчанию.
```yaml
runbookOutput:
schema: stewardship/adoption-assessment@0.1
repository:
path: Infra/LXD
baselineRevision: 0123456789abcdef
dirty: false
classification:
proposedType: infrastructure-config
confidence: high
evidence:
- profiles-source/*.yaml
- scripts/sync-from-cluster.sh
confirmationRequired: true
entrypoints:
claude: CLAUDE.md
portable: AGENTS.md
canonicalDirection: legacy-claude-to-agents
knowledge:
- path: kdb.yaml
format: legacy-yaml
action: wrap
proposedContentRoots:
- id: lxd-profile-sources
path: profiles-source
role: profiles
authority: source
collisions: []
findings:
- severity: warning
code: ADOPT_ENTRYPOINT_DIRECTION_LEGACY
path: AGENTS.md
questions:
- Confirm owner and lifecycle
```
Assessment MUST distinguish `detected`, `inferred` and `confirmed` values.
## 9. Phase 3 — confirmation boundary
До построения финального plan владелец должен подтвердить только решения, которые нельзя надёжно вывести:
- repository type при confidence ниже `high`;
- owner;
- lifecycle/access;
- какие paths являются source of truth;
- спорные cross-repository ownership boundaries;
- допустимость изменения существующих entrypoints.
Остальные безопасные defaults могут быть предложены в plan без отдельного диалога.
## 10. Phase 4 — adoption plan
Plan строится относительно immutable baseline revision и содержит только операции `create`, `patch-managed-block` или `preserve`.
```yaml
runbookOutput:
schema: stewardship/adoption-plan@0.1
repository: repo:infra-lxd
baselineRevision: 0123456789abcdef
strategy: overlay
changes:
- action: create
path: ops/contract.yaml
ownership: stewardship
- action: create
path: kdb/kdb.yaml
ownership: stewardship
reason: Compatibility index for legacy root kdb.yaml
- action: preserve
path: kdb.yaml
ownership: repository
- action: patch-managed-block
path: CLAUDE.md
ownership: shared
optional: true
forbiddenChanges:
- profiles-source/**
- profiles/**
- .ssh/**
validations:
- stewardship-schema
- path-confinement
- knowledge-references
- agent-entrypoint-cycle
approval:
required: true
planHash: sha256:0123456789abcdef
```
Plan MUST содержать rendered file contents или exact patch для каждого `create`/`patch-managed-block`, а не только словесное описание.
## 11. Compatibility rules
### 11.1. KDB
| Состояние | Действие |
|---|---|
| KDB отсутствует | создать `kdb/kdb.yaml` |
| `kdb/kdb.yaml` уже соответствует Stewardship | использовать без переписывания |
| legacy KDB находится в другом path | создать `kdb/kdb.yaml` как небольшой index/adapter |
| legacy/custom KDB уже занимает `kdb/kdb.yaml` | создать `ops/knowledge.yaml` и указать его в contract |
| несколько knowledge sources | index с topics/documents и явным authority |
Compatibility index MAY ссылаться на legacy YAML sections через `Topic.data.x-selector`, но не должен копировать весь legacy source.
```yaml
apiVersion: stewardship.corsus.ru/v1alpha1
kind: KnowledgeBase
metadata:
name: antivirus-knowledge-index
spec:
repository: repo:services-antivirus
defaultLanguage: ru
topics:
- id: windows-agent-rollout
summary: Verified Windows agent rollout
intents: [endpoint.deploy]
documents: [legacy-antivirus-kdb]
data:
x-selector:
format: yaml-path
value: $.windows_agent_rollout
documents:
- id: legacy-antivirus-kdb
title: Existing Antivirus knowledge base
role: reference
path: kdb/kdb.yaml
mediaType: application/yaml
authority: local-canonical
status: verified
```
### 11.2. `CLAUDE.md` и `AGENTS.md`
| Состояние | Действие |
|---|---|
| оба отсутствуют | создать короткий `AGENTS.md` и импортирующий его `CLAUDE.md` |
| только `AGENTS.md` | создать короткий `CLAUDE.md` с импортом |
| только `CLAUDE.md` | сохранить; предложить минимальный portable `AGENTS.md` |
| оба есть и согласованы | сохранить, добавить только contract pointer при необходимости |
| `AGENTS.md` ссылается на `CLAUDE.md` | не создавать обратный импорт; зарегистрировать legacy direction warning |
| файлы противоречат друг другу | остановить автоматическую консолидацию и запросить owner decision |
Изменение shared entrypoint SHOULD выполняться через ограниченный managed block с markers, а не заменой всего файла.
### 11.3. Existing skills and handlers
- сохранить paths;
- не копировать implementation между `.claude/skills`, `.agents/skills` и `ops/handlers`;
- на L1 только описать существование и safety boundary;
- переносить implementation в canonical handler только отдельным L2 plan.
### 11.4. SSH и secrets
- записывать только факт наличия path и назначение, если оно уже документировано;
- не вычислять fingerprints private keys без явной необходимости;
- не переносить keys в стандартный каталог;
- рекомендовать repository-scoped key как отдельную follow-up задачу;
- найденный tracked secret является blocker, но его remediation не входит автоматически в adoption apply.
### 11.5. Normalization recipe `documents-to-content-root`
Эта recipe MAY использоваться только по явному запросу владельца. Она не является частью default overlay.
```yaml
normalizationRecipe:
id: documents-to-content-root
strategy: normalize
sourceScope: repository-root
targetRoot: docs
filenameStyle: kebab-case
preserveAtRoot:
- README.md
- AGENTS.md
- CLAUDE.md
- CONTRIBUTING.md
- SECURITY.md
- CODE_OF_CONDUCT.md
- LICENSE
- LICENSE.*
- CHANGELOG.md
authorityPartitions:
canonical: docs
research: docs/research
rewriteReferences:
- ops/contract.yaml
- kdb/kdb.yaml
- Markdown links
- Markdown frontmatter
- managed agent instruction blocks
approvalRequired: true
```
Алгоритм recipe:
1. Найти project-specific long-form documents в корне, но не считать любой `*.md` кандидатом на перенос.
2. Оставить universal entrypoints, license/community files и tool-required root manifests на месте.
3. Классифицировать каждый кандидат как canonical, runbook, research или `preserve`.
4. Построить явный `oldPath → newPath` map. Переименование в kebab-case является отдельной видимой частью plan.
5. Проверить collisions с учётом case-insensitive filesystems и уже существующих targets.
6. Построить reference index до записи.
7. Переписать repo-relative ссылки в contract, KDB, frontmatter, Markdown и managed instruction blocks.
8. Не переписывать произвольные совпадения в source code, logs, vendor snapshots или evidence без отдельного правила.
9. Показать rename map и exact patches владельцу.
10. После approval выполнить moves и reference rewrites как один local change set.
Пример plan fragment:
```yaml
normalization:
recipe: documents-to-content-root
moves:
- from: REPOSITORY_STEWARDSHIP_SPEC.md
to: docs/specification.md
authority: canonical
- from: INFRASTRUCTURE_OPERATIONS_ARCHITECTURE_OPTIONS.md
to: docs/research/infrastructure-operations-architecture-options.md
authority: research
referenceUpdates:
- ops/contract.yaml
- kdb/kdb.yaml
- README.md
- AGENTS.md
preservedRootEntrypoints:
- README.md
- AGENTS.md
- CLAUDE.md
```
Recipe MUST завершиться проверкой отсутствующих targets, старых broken references, Markdown links, frontmatter paths и KDB document paths. Она MUST NOT перемещать domain-native artifacts под `docs/`.
## 12. Phase 5 — apply
Перед записью повторно проверить HEAD и status. Если baseline изменился, plan считается stale и строится заново.
Apply выполняет только подтверждённые changes:
1. создаёт `ops/contract.yaml`;
2. создаёт новый KDB index/adapter только в свободном path;
3. создаёт или патчит ограниченные managed blocks entrypoints;
4. записывает template lineage с `mode: adopted-overlay` и точным `managedPaths`;
5. не вызывает external operations;
6. показывает итоговый diff.
При `strategy: normalize` apply дополнительно выполняет только rename map и reference rewrites именованной recipe. Любой новый move инвалидирует approval и требует нового plan hash.
Apply не делает commit или push, если пользователь не запросил это отдельно.
## 13. Phase 6 — verify
Обязательные проверки:
- YAML parse и schema validation;
- repo-relative path confinement;
- существование всех content roots и documents;
- отсутствие циклов entrypoint imports;
- intent выбирает ожидаемые topics, но не весь KDB;
- selector находит ожидаемые domain artifacts;
- source/mirror authority не перепутаны;
- legacy files byte-identical, если plan обещал `preserve`;
- old paths из rename map больше не используются в active references;
- все new paths из rename map существуют;
- diff ограничен approved paths;
- catalog rebuild детерминирован;
- external state не изменялся.
Результат:
```yaml
runbookOutput:
schema: stewardship/adoption-report@0.1
repository: repo:infra-lxd
baselineRevision: 0123456789abcdef
compatibilityLevel: L1
outcome: pass-with-warnings
changedPaths:
- ops/contract.yaml
- kdb/kdb.yaml
preservedPaths:
- profiles-source
- profiles
- kdb.yaml
unresolvedFindings:
- ADOPT_ENTRYPOINT_DIRECTION_LEGACY
```
## 14. Finding codes
```yaml
findingCodes:
ADOPT_TYPE_AMBIGUOUS: confirmation-required
ADOPT_OWNER_UNKNOWN: confirmation-required
ADOPT_WORKTREE_DIRTY: warning
ADOPT_PATH_COLLISION: blocker
ADOPT_KDB_LEGACY: info
ADOPT_KDB_CANONICAL_PATH_OCCUPIED: warning
ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
ADOPT_ENTRYPOINT_CONFLICT: blocker
ADOPT_SECRET_TRACKED: blocker
ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required
ADOPT_BASELINE_CHANGED: blocker
ADOPT_EXTERNAL_WRITE_DETECTED: blocker
ADOPT_VALIDATION_FAILED: blocker
ADOPT_ROOT_DOCUMENT_CANDIDATE: info
ADOPT_MOVE_COLLISION: blocker
ADOPT_REFERENCE_REWRITE_INCOMPLETE: blocker
```
Коды стабильнее текстов и пригодны для CLI, CI и каталога.
## 15. Rollout waves
Начинать следует не с самых простых репозиториев, а с двух репрезентативных сложных cases — это раньше выявит недостатки модели.
```mermaid
flowchart LR
W0["Wave 0: fixtures"] --> W1["Wave 1: LXD + Antivirus"]
W1 --> G1{"Schema holds?"}
G1 -->|нет| FIX["Исправить schema/runbook"]
FIX --> W1
G1 -->|да| W2["Wave 2: Docker, Network, Monitoring, Surveillance"]
W2 --> W3["Wave 3: remaining Infra and Services"]
W3 --> W4["Wave 4: software and project repositories"]
```
Для каждой wave:
1. выполнить assessment всех repositories;
2. сгруппировать одинаковые findings;
3. обновить runbook/template один раз;
4. построить отдельный plan для каждого repository;
5. применить через reviewable branch/PR;
6. измерить time-to-context и объём прочитанного контекста;
7. только затем расширять следующую wave.
Outliers с неясным owner, secrets или конфликтующей authority помечаются `deferred` и не блокируют rollout остальных.
## 16. Предлагаемый Claude skill
После стабилизации первых двух pilot plans создать skill `repository-adoption`.
```yaml
skillProposal:
name: repository-adoption
purpose: Assess and prepare an existing repository for Repository Stewardship
canonicalProcedure: docs/adoption-runbook.md
defaultMode: plan
allowedByDefault:
- read repository metadata
- classify repository
- produce assessment
- produce proposed diff
approvalRequired:
- write files
- move or delete files
- commit or push
- access secrets
- contact external systems
forbidden:
- duplicate repoctl logic
- silently rewrite legacy KDB
- execute discovered handlers during assessment
```
Предлагаемый вызов для Claude:
```text
/repository-adoption C:\Users\alexander.baranov\Git\Infra\LXD --mode plan
```
До появления `repoctl adopt` skill выполняет runbook напрямую. После появления CLI он становится тонким wrapper: собирает недостающие решения пользователя, запускает команду и объясняет findings.
## 17. Что заимствовано из внешних практик
| Практика | Что используем |
|---|---|
| [Backstage component registration](https://backstage.io/docs/getting-started/register-a-component/) | сначала анализ существующего repository, затем review/import; descriptor добавляется PR |
| [Backstage catalog graph](https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph/) | repo-local YAML как source of truth; автоматическая классификация только начальная, metadata управляет человек |
| [Renovate onboarding](https://docs.renovatebot.com/getting-started/installing-onboarding/) | onboarding PR является безопасным gate; до merge другие изменения не выполняются |
| [Copier updates](https://copier.readthedocs.io/en/stable/updating/) | template lineage, сохранённые answers, versioned update и явная обработка conflicts |
| [OpenRewrite dry run](https://docs.openrewrite.org/reference/rewrite-maven-plugin) | recipe discovery, dry-run patch, review перед применением и возможность CI gate |
| [GitHub organization rulesets](https://docs.github.com/en/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) | rollout waves можно выбирать по repository properties, а enforcement включать после пилота |
Вывод из сравнения: adoption должен быть не генератором файлов, а повторяемым конвейером `discover → assess → plan → review → apply → verify`, где до review нет записи, а полезное содержимое репозитория не становится собственностью шаблона.
## 18. Definition of done
Repository считается adopted, когда:
- существует валидный `ops/contract.yaml`;
- тип, owner, lifecycle и content roots подтверждены;
- агент находит authoritative result paths без полного обхода дерева;
- intent получает небольшой релевантный KDB context;
- legacy KDB и domain content сохранены;
- `CLAUDE.md` остаётся основной Claude-точкой входа;
- portable instructions доступны через `AGENTS.md`, без import cycle;
- contract виден в производном catalog;
- unresolved warnings перечислены, имеют owner или осознанно deferred;
- diff и validation evidence доступны для review.
L2 operations, нормализация дерева, замена credentials и исправление найденных domain problems являются отдельными follow-up changes, а не скрытой частью adoption.