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