29 KiB
documentId, documentVersion, protocol, schemaApiVersion, status, normative, language, machineSpecification, humanGuide, defaultStrategy, primaryAgent, portable
| documentId | documentVersion | protocol | schemaApiVersion | status | normative | language | machineSpecification | humanGuide | defaultStrategy | primaryAgent | portable |
|---|---|---|---|---|---|---|---|---|---|---|---|
| repository-adoption-runbook | 0.1.0 | Repository Stewardship | stewardship.corsus.ru/v1alpha1 | proposed | false | ru | docs/specification.md | docs/guide.md | overlay | Claude | true |
Repository Adoption Runbook
0. Назначение и решение
Этот runbook подключает существующий Git-репозиторий к Repository Stewardship без перестройки его полезного содержимого.
Рекомендованная реализация состоит из двух слоёв:
- этот runbook — переносимый источник истины для человека и любого агента;
- тонкий 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: большой customkdb/kdb.yaml, vendor sources, policies и ссылки на authoritative artifacts в LXD/Network/Docker;Services/MonitoringиServices/Surveillance: уже имеют KDB и domain-specific tools, но не одинаковые agent entrypoints.
Общий интерфейс здесь полезнее общего физического дерева. Adoption объявляет существующие места через contract и compatibility index.
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
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. После реализации им соответствуют:
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
Проверить существование:
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;
- кто реально владеет изменением.
Примеры:
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 по умолчанию.
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.
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.
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.
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:
- Найти project-specific long-form documents в корне, но не считать любой
*.mdкандидатом на перенос. - Оставить universal entrypoints, license/community files и tool-required root manifests на месте.
- Классифицировать каждый кандидат как canonical, runbook, research или
preserve. - Построить явный
oldPath → newPathmap. Переименование в kebab-case является отдельной видимой частью plan. - Проверить collisions с учётом case-insensitive filesystems и уже существующих targets.
- Построить reference index до записи.
- Переписать repo-relative ссылки в contract, KDB, frontmatter, Markdown и managed instruction blocks.
- Не переписывать произвольные совпадения в source code, logs, vendor snapshots или evidence без отдельного правила.
- Показать rename map и exact patches владельцу.
- После approval выполнить moves и reference rewrites как один local change set.
Пример plan fragment:
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:
- создаёт
ops/contract.yaml; - создаёт новый KDB index/adapter только в свободном path;
- создаёт или патчит ограниченные managed blocks entrypoints;
- записывает template lineage с
mode: adopted-overlayи точнымmanagedPaths; - не вызывает external operations;
- показывает итоговый 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 не изменялся.
Результат:
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
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 — это раньше выявит недостатки модели.
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:
- выполнить assessment всех repositories;
- сгруппировать одинаковые findings;
- обновить runbook/template один раз;
- построить отдельный plan для каждого repository;
- применить через reviewable branch/PR;
- измерить time-to-context и объём прочитанного контекста;
- только затем расширять следующую wave.
Outliers с неясным owner, secrets или конфликтующей authority помечаются deferred и не блокируют rollout остальных.
16. Предлагаемый Claude skill
После стабилизации первых двух pilot plans создать skill repository-adoption.
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:
/repository-adoption C:\Users\alexander.baranov\Git\Infra\LXD --mode plan
До появления repoctl adopt skill выполняет runbook напрямую. После появления CLI он становится тонким wrapper: собирает недостающие решения пользователя, запускает команду и объясняет findings.
17. Что заимствовано из внешних практик
| Практика | Что используем |
|---|---|
| Backstage component registration | сначала анализ существующего repository, затем review/import; descriptor добавляется PR |
| Backstage catalog graph | repo-local YAML как source of truth; автоматическая классификация только начальная, metadata управляет человек |
| Renovate onboarding | onboarding PR является безопасным gate; до merge другие изменения не выполняются |
| Copier updates | template lineage, сохранённые answers, versioned update и явная обработка conflicts |
| OpenRewrite dry run | recipe discovery, dry-run patch, review перед применением и возможность CI gate |
| GitHub organization rulesets | 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.