661 lines
29 KiB
Markdown
661 lines
29 KiB
Markdown
---
|
||
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.
|