docs: baseline specification-only repository stewardship
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user