The rule that a knowledge file's format comes from validating it, never from the path it occupies, was applied to `kdb/kdb.yaml` and stopped there. The first branch of _plan_knowledge declared `ops/knowledge.yaml` the entrypoint without ever looking at its assessed action, so a repository holding a non-conformant file at the adapter path was adopted with the contract pointing straight at something that fails the KnowledgeBase schema -- the same defect, one path over, with the same consequence: it surfaces only at verify and gets repaired by hand outside the approved plan hash. assess had the answer all along and build_plan discarded it. Choosing the free canonical slot makes several legacy sources reachable at once, so the generated index registers all of them rather than the first; indexing one and dropping the rest in silence would be a new instance of the omission runbook 11.1 exists to prevent. That also implements the table's last row, which had no branch until now. When both canonical paths hold non-conformant files there is no free slot and neither occupant may be overwritten, so adoption refuses to plan. The plan schema is closed and carries no findings field, which leaves nowhere to record a decision left unresolved -- the same reason malformed markers raise instead of being guessed at. - gate the adapter branch on the assessed action, not on the file existing - give each indexed document an id derived from its own path - add ADOPT_KNOWLEDGE_UNRESOLVED for the dead end, and document it - bind the four previously untested rows of 11.1 to the parametrized table Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
697 lines
36 KiB
Markdown
697 lines
36 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 --type TYPE --answers ANSWERS --output yaml
|
||
repoctl adopt --repo PATH --mode apply --plan PLAN --approve PLAN_HASH
|
||
repoctl adopt --repo PATH --mode verify --plan PLAN --output yaml
|
||
```
|
||
|
||
Тип репозитория подтверждается через `--type` или ключ `repositoryType` в `--answers`; без этого `assess` задаёт вопрос, на который нечем ответить. Подтверждение фиксируется в `metadata.annotations` контракта, чтобы осознанное решение владельца отличалось от непроверенной догадки классификатора.
|
||
|
||
`migrate` — обновление уже подключённого репозитория между версиями schema/template — определён в разделе 1, но **не реализован**. Сейчас повторный `adopt` на подключённом репозитории возвращает `preserve` для всех путей; правки уже принятого contract выполняются вне plan/approve и являются известным ограничением L1.
|
||
|
||
## 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 |
|
||
| `ops/knowledge.yaml` уже соответствует Stewardship | использовать без переписывания; занятый `kdb/kdb.yaml` — preserve и forbid |
|
||
| legacy/custom файл занимает `ops/knowledge.yaml`, а `kdb/kdb.yaml` свободен | создать `kdb/kdb.yaml` как index; занятый adapter path — preserve и forbid |
|
||
| оба canonical path заняты non-conformant файлами | отказать в `plan` с `ADOPT_KNOWLEDGE_UNRESOLVED` |
|
||
| несколько knowledge sources | index с topics/documents и явным authority; регистрируются **все** источники |
|
||
|
||
Выбор строки определяется **валидацией содержимого** против schema `KnowledgeBase`, а не расположением файла. Файл не является conformant KDB только потому, что лежит в каноническом path: ранняя реализация делала именно это допущение и в результате указывала contract на файл, не проходящий schema, что обнаруживалось только на `verify`.
|
||
|
||
Это правило распространяется на `ops/knowledge.yaml` ровно так же, как на `kdb/kdb.yaml`. Adapter path — это место, куда adoption **кладёт** сгенерированный index, а не доказательство того, что лежащий там файл им является.
|
||
|
||
Последняя строка — тупик, а не выбор по умолчанию. Свободного canonical path под conformant index не остаётся, а перезапись любого из двух занятых противоречит разделу 3; schema `adoption-plan` закрыта и поля findings не имеет, поэтому записать нерешённое решение в план некуда. Adoption отказывается планировать и оставляет разрешение конфликта владельцу.
|
||
|
||
Сгенерированный index создаётся с пустым `topics`. Какие секции legacy source заслуживают отдельного intent — решение владельца, а не вывод инструмента: adoption регистрирует документ и оставляет routing на осознанный следующий шаг.
|
||
|
||
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` | сохранить содержимое, добавить managed block с pointer; создать минимальный portable `AGENTS.md` |
|
||
| оба есть и согласованы | сохранить, добавить только contract pointer при необходимости |
|
||
| `AGENTS.md` ссылается на `CLAUDE.md` | не создавать обратный импорт; зарегистрировать legacy direction warning |
|
||
| файлы противоречат друг другу | остановить автоматическую консолидацию и запросить owner decision |
|
||
|
||
Изменение shared entrypoint MUST выполняться через ограниченный managed block с markers `<!-- stewardship:managed:start -->` и `<!-- stewardship:managed:end -->`, а не заменой всего файла. Блок вставляется под первым заголовком первого уровня, чтобы pointer оказался выше основного текста. Повторный `plan` на уже пропатченном файле даёт `preserve`, поэтому adoption идемпотентна. Несогласованные или дублирующиеся markers — в файле или во вставляемом блоке — являются ошибкой `ADOPT_MANAGED_BLOCK_MALFORMED`, а не поводом угадывать границу.
|
||
|
||
### 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`
|
||
|
||
> **Не реализовано на L1.** `--strategy normalize` и `--recipe` не предлагаются CLI: пока нет canonical handler и validation path, объявлять операцию существующей нельзя. Раздел описывает целевое поведение, а не доступную команду.
|
||
|
||
Эта 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
|
||
|
||
Выполняются на L1 (`repoctl adopt --mode verify --plan <файл>`):
|
||
|
||
- YAML parse и schema validation;
|
||
- repo-relative path confinement;
|
||
- существование всех content roots и documents;
|
||
- отсутствие циклов entrypoint imports;
|
||
- `preserve`-пути не изменены — иначе `ADOPT_PRESERVED_MODIFIED` и `outcome: fail`;
|
||
- изменения не выходят за пределы путей плана — иначе `ADOPT_DIFF_OUTSIDE_PLAN`;
|
||
- baseline плана совпадает с текущим HEAD — иначе `ADOPT_BASELINE_CHANGED`.
|
||
|
||
`verify` без `--plan` не имеет эталона для сравнения и возвращает `ADOPT_REPORT_UNSCOPED`. Пустые `changedPaths`/`preservedPaths` в таком отчёте означают «ничего не проверено», а не «ничего не изменено», и не являются доказательством успешной adoption.
|
||
|
||
Отложено вместе с normalization и L3 Plan, пока не реализовано:
|
||
|
||
- intent выбирает ожидаемые topics, но не весь KDB;
|
||
- selector находит ожидаемые domain artifacts;
|
||
- source/mirror authority не перепутаны;
|
||
- old paths из rename map больше не используются в active references;
|
||
- все new paths из rename map существуют;
|
||
- 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_SECRET_SHAPED_UNTRACKED: info
|
||
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
|
||
ADOPT_PATH_OUTSIDE_REPOSITORY: blocker
|
||
ADOPT_FORBIDDEN_PATH: blocker
|
||
ADOPT_MANAGED_BLOCK_MALFORMED: blocker
|
||
ADOPT_KNOWLEDGE_UNRESOLVED: blocker
|
||
ADOPT_PRESERVED_MODIFIED: blocker
|
||
ADOPT_DIFF_OUTSIDE_PLAN: warning
|
||
ADOPT_REPORT_UNSCOPED: warning
|
||
APPROVAL_FAILED: blocker
|
||
```
|
||
|
||
`ADOPT_SECRET_TRACKED` относится только к **tracked** путям. Untracked путь с secret-shaped именем получает отдельный `ADOPT_SECRET_SHAPED_UNTRACKED`, а путь, который репозиторий явно игнорирует, не сообщается вовсе: blocker-код, срабатывающий на игнорируемых файлах, приучает игнорировать blocker.
|
||
|
||
`ADOPT_WORKTREE_DIRTY` на этапе `assess` остаётся warning и не мешает планированию. На этапе `apply` он становится 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.
|