Files
repoctl/docs/adoption-runbook.md
T

29 KiB
Raw Blame History

documentId, documentVersion, protocol, schemaApiVersion, status, normative, language, machineSpecification, humanGuide, defaultStrategy, primaryAgent, portable
documentId documentVersion protocol schemaApiVersion status normative language machineSpecification humanGuide defaultStrategy primaryAgent portable
repository-adoption-runbook 0.1.0 Repository Stewardship stewardship.corsus.ru/v1alpha1 proposed false ru docs/specification.md docs/guide.md overlay Claude true

Repository Adoption Runbook

0. Назначение и решение

Этот runbook подключает существующий Git-репозиторий к Repository Stewardship без перестройки его полезного содержимого.

Рекомендованная реализация состоит из двух слоёв:

  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.

flowchart LR
    LEGACY["Существующий layout"] --> OVERLAY["Stewardship overlay"]
    OVERLAY --> CONTRACT["ops/contract.yaml"]
    OVERLAY --> KNOWLEDGE["KnowledgeBase index or adapter"]
    OVERLAY --> ENTRY["CLAUDE.md + AGENTS.md pointers"]
    CONTRACT --> ROOTS["Existing contentRoots stay in place"]
    KNOWLEDGE --> SOURCES["Existing KDB and vendor sources stay in place"]

3. Safety invariants

Во время adoption агент или инструмент MUST:

  • выполнять assess и plan только на чтение;
  • не читать и не выводить содержимое private keys, tokens, passwords, .env и secret stores;
  • не выполнять обнаруженные scripts, hooks, skills или operations;
  • не подключаться к серверам и не изменять external systems;
  • не перемещать, не удалять и не переименовывать существующие файлы;
  • не переписывать существующие KDB и agent instructions целиком;
  • не менять Git remote, default branch, history, permissions или access scope;
  • не коммитить и не отправлять изменения без отдельного запроса;
  • показать proposed diff до apply;
  • остановить apply, если baseline revision изменился после plan;
  • сохранять неизвестные x-* поля и существующие пользовательские секции.

Dirty working tree не мешает assess, но MUST быть явно отмечен. Для apply SHOULD использоваться чистая отдельная ветка либо подтверждённый набор непересекающихся paths.

4. Режимы adoption

adoptionModes:
  assess:
    writes: false
    output: AdoptionAssessment
  plan:
    writes: false
    output: AdoptionPlan
  apply:
    writes: repository-local
    approvalRequired: true
    allowedScope: proposedPathsOnly
  verify:
    writes: false
    output: AdoptionReport

До реализации CLI эти режимы являются логическими этапами runbook. После реализации им соответствуют:

repoctl adopt --repo PATH --mode assess --output yaml
repoctl adopt --repo PATH --mode plan --output yaml
repoctl adopt --repo PATH --mode apply --plan PLAN --approve PLAN_HASH
repoctl adopt --repo PATH --mode verify --output yaml

5. Входные данные

Минимально необходимы:

  • локальный путь или repository URL;
  • read access;
  • ожидаемый owner, если он уже известен;
  • scope: один repository или явно перечисленная rollout wave.

Полезны, но не обязательны:

  • предполагаемый repository type;
  • ссылка на Git hosting project;
  • известные связанные repositories;
  • выбранный template version;
  • сведения о protected branch/CODEOWNERS.

Отсутствующие сведения становятся questions, а не догадками, записанными как fact.

6. Phase 1 — preflight

6.1. Найти границу репозитория

Определить ближайший корень с .git. Nested repositories оцениваются отдельно. Каталог, содержащий несколько repositories, не получает один общий contract вместо них.

6.2. Зафиксировать Git baseline

Собрать без изменения состояния:

  • current branch;
  • HEAD revision;
  • наличие staged, modified и untracked paths;
  • remotes без credentials;
  • tracked/untracked status будущих stewardship paths.

Не включать содержимое diff в централизованный отчёт без необходимости: для планирования достаточно списка paths и локального review.

6.3. Проверить collisions

Проверить существование:

ops/contract.yaml
kdb/kdb.yaml
kdb.yaml
CLAUDE.md
AGENTS.md
.claude/skills/
.agents/skills/
ops/handlers/
ops/template-answers.yaml

Существующий path никогда не считается свободным только потому, что его формат неизвестен.

7. Phase 2 — assessment

7.1. Определить repository type

Тип выбирается по основному результату работы, а не по имени родительского каталога.

Основной результат Type
desired infrastructure state, inventory, profiles, networks, stacks infrastructure-config
конфигурация и эксплуатационная модель конкретного сервиса service-config
компилируемый/исполняемый код, library или application software
документы, решения, datasets и deliverables проекта project

Если evidence указывает на два типа, выбрать владельца основного результата, а второй аспект отразить labels/content roots. Не создавать новый type только из-за смешанного layout.

7.2. Найти authoritative content

Для каждого значимого path определить:

  • role;
  • source, generated, observed, mirror или evidence;
  • write policy;
  • selector;
  • кто реально владеет изменением.

Примеры:

contentRoots:
  - id: lxd-profile-sources
    role: profiles
    path: profiles-source
    kind: file-set
    authority: source
    writePolicy: managed
    selector: "*.yaml"
  - id: lxd-live-profile-mirror
    role: observed
    path: profiles
    kind: file-set
    authority: mirror
    writePolicy: generated
    selector: "*.yaml"
  - id: docker-stacks
    role: stacks
    path: .
    kind: file-set
    authority: source
    writePolicy: managed
    selector: "*/compose.y*ml"

Нельзя объявлять mirror как source только потому, что его YAML выглядит полнее.

7.3. Найти знания и provenance

Для каждого KDB/document source записать:

  • path или URI;
  • фактический формат;
  • размер и верхнеуровневую структуру без загрузки всего содержимого в agent context;
  • наличие index/routing;
  • authority и status;
  • vendor/local/observed provenance;
  • freshness signals;
  • наличие потенциальных secret-shaped paths или keys без вывода values.

7.4. Найти agent entrypoints и automation

Определить:

  • какой файл сейчас является фактическим источником инструкций;
  • есть ли противоречия или циклические ссылки между CLAUDE.md и AGENTS.md;
  • какие skills/handlers каноничны;
  • какие команды являются read-only, а какие меняют local/external state;
  • где описан verify.

Наличие Claude-specific skill не делает его переносимым handler. В contract сначала регистрируется семантика операции, а адаптация skill выполняется позднее на L2.

7.5. Найти cross-repository relations

Записывать отношения по authority, а не по случайным относительным путям:

  • service requirement → infrastructure capability;
  • local pointer → authoritative artifact in provider repository;
  • generated mirror → source root;
  • runbook → operation/handler;
  • vendor source → derived local knowledge.

8. Машиночитаемый результат assessment

До появления стабильного protocol kind используется versioned runbook output. Он не коммитится в целевой repository по умолчанию.

runbookOutput:
  schema: stewardship/adoption-assessment@0.1
  repository:
    path: Infra/LXD
    baselineRevision: 0123456789abcdef
    dirty: false
  classification:
    proposedType: infrastructure-config
    confidence: high
    evidence:
      - profiles-source/*.yaml
      - scripts/sync-from-cluster.sh
    confirmationRequired: true
  entrypoints:
    claude: CLAUDE.md
    portable: AGENTS.md
    canonicalDirection: legacy-claude-to-agents
  knowledge:
    - path: kdb.yaml
      format: legacy-yaml
      action: wrap
  proposedContentRoots:
    - id: lxd-profile-sources
      path: profiles-source
      role: profiles
      authority: source
  collisions: []
  findings:
    - severity: warning
      code: ADOPT_ENTRYPOINT_DIRECTION_LEGACY
      path: AGENTS.md
  questions:
    - Confirm owner and lifecycle

Assessment MUST distinguish detected, inferred and confirmed values.

9. Phase 3 — confirmation boundary

До построения финального plan владелец должен подтвердить только решения, которые нельзя надёжно вывести:

  • repository type при confidence ниже high;
  • owner;
  • lifecycle/access;
  • какие paths являются source of truth;
  • спорные cross-repository ownership boundaries;
  • допустимость изменения существующих entrypoints.

Остальные безопасные defaults могут быть предложены в plan без отдельного диалога.

10. Phase 4 — adoption plan

Plan строится относительно immutable baseline revision и содержит только операции create, patch-managed-block или preserve.

runbookOutput:
  schema: stewardship/adoption-plan@0.1
  repository: repo:infra-lxd
  baselineRevision: 0123456789abcdef
  strategy: overlay
  changes:
    - action: create
      path: ops/contract.yaml
      ownership: stewardship
    - action: create
      path: kdb/kdb.yaml
      ownership: stewardship
      reason: Compatibility index for legacy root kdb.yaml
    - action: preserve
      path: kdb.yaml
      ownership: repository
    - action: patch-managed-block
      path: CLAUDE.md
      ownership: shared
      optional: true
  forbiddenChanges:
    - profiles-source/**
    - profiles/**
    - .ssh/**
  validations:
    - stewardship-schema
    - path-confinement
    - knowledge-references
    - agent-entrypoint-cycle
  approval:
    required: true
    planHash: sha256:0123456789abcdef

Plan MUST содержать rendered file contents или exact patch для каждого create/patch-managed-block, а не только словесное описание.

11. Compatibility rules

11.1. KDB

Состояние Действие
KDB отсутствует создать kdb/kdb.yaml
kdb/kdb.yaml уже соответствует Stewardship использовать без переписывания
legacy KDB находится в другом path создать kdb/kdb.yaml как небольшой index/adapter
legacy/custom KDB уже занимает kdb/kdb.yaml создать ops/knowledge.yaml и указать его в contract
несколько knowledge sources index с topics/documents и явным authority

Compatibility index MAY ссылаться на legacy YAML sections через Topic.data.x-selector, но не должен копировать весь legacy source.

apiVersion: stewardship.corsus.ru/v1alpha1
kind: KnowledgeBase
metadata:
  name: antivirus-knowledge-index
spec:
  repository: repo:services-antivirus
  defaultLanguage: ru
  topics:
    - id: windows-agent-rollout
      summary: Verified Windows agent rollout
      intents: [endpoint.deploy]
      documents: [legacy-antivirus-kdb]
      data:
        x-selector:
          format: yaml-path
          value: $.windows_agent_rollout
  documents:
    - id: legacy-antivirus-kdb
      title: Existing Antivirus knowledge base
      role: reference
      path: kdb/kdb.yaml
      mediaType: application/yaml
      authority: local-canonical
      status: verified

11.2. CLAUDE.md и AGENTS.md

Состояние Действие
оба отсутствуют создать короткий AGENTS.md и импортирующий его CLAUDE.md
только AGENTS.md создать короткий CLAUDE.md с импортом
только CLAUDE.md сохранить; предложить минимальный portable AGENTS.md
оба есть и согласованы сохранить, добавить только contract pointer при необходимости
AGENTS.md ссылается на CLAUDE.md не создавать обратный импорт; зарегистрировать legacy direction warning
файлы противоречат друг другу остановить автоматическую консолидацию и запросить owner decision

Изменение shared entrypoint SHOULD выполняться через ограниченный managed block с markers, а не заменой всего файла.

11.3. Existing skills and handlers

  • сохранить paths;
  • не копировать implementation между .claude/skills, .agents/skills и ops/handlers;
  • на L1 только описать существование и safety boundary;
  • переносить implementation в canonical handler только отдельным L2 plan.

11.4. SSH и secrets

  • записывать только факт наличия path и назначение, если оно уже документировано;
  • не вычислять fingerprints private keys без явной необходимости;
  • не переносить keys в стандартный каталог;
  • рекомендовать repository-scoped key как отдельную follow-up задачу;
  • найденный tracked secret является blocker, но его remediation не входит автоматически в adoption apply.

11.5. Normalization recipe documents-to-content-root

Эта recipe MAY использоваться только по явному запросу владельца. Она не является частью default overlay.

normalizationRecipe:
  id: documents-to-content-root
  strategy: normalize
  sourceScope: repository-root
  targetRoot: docs
  filenameStyle: kebab-case
  preserveAtRoot:
    - README.md
    - AGENTS.md
    - CLAUDE.md
    - CONTRIBUTING.md
    - SECURITY.md
    - CODE_OF_CONDUCT.md
    - LICENSE
    - LICENSE.*
    - CHANGELOG.md
  authorityPartitions:
    canonical: docs
    research: docs/research
  rewriteReferences:
    - ops/contract.yaml
    - kdb/kdb.yaml
    - Markdown links
    - Markdown frontmatter
    - managed agent instruction blocks
  approvalRequired: true

Алгоритм recipe:

  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:

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 не изменялся.

Результат:

runbookOutput:
  schema: stewardship/adoption-report@0.1
  repository: repo:infra-lxd
  baselineRevision: 0123456789abcdef
  compatibilityLevel: L1
  outcome: pass-with-warnings
  changedPaths:
    - ops/contract.yaml
    - kdb/kdb.yaml
  preservedPaths:
    - profiles-source
    - profiles
    - kdb.yaml
  unresolvedFindings:
    - ADOPT_ENTRYPOINT_DIRECTION_LEGACY

14. Finding codes

findingCodes:
  ADOPT_TYPE_AMBIGUOUS: confirmation-required
  ADOPT_OWNER_UNKNOWN: confirmation-required
  ADOPT_WORKTREE_DIRTY: warning
  ADOPT_PATH_COLLISION: blocker
  ADOPT_KDB_LEGACY: info
  ADOPT_KDB_CANONICAL_PATH_OCCUPIED: warning
  ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
  ADOPT_ENTRYPOINT_CONFLICT: blocker
  ADOPT_SECRET_TRACKED: blocker
  ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required
  ADOPT_BASELINE_CHANGED: blocker
  ADOPT_EXTERNAL_WRITE_DETECTED: blocker
  ADOPT_VALIDATION_FAILED: blocker
  ADOPT_ROOT_DOCUMENT_CANDIDATE: info
  ADOPT_MOVE_COLLISION: blocker
  ADOPT_REFERENCE_REWRITE_INCOMPLETE: blocker

Коды стабильнее текстов и пригодны для CLI, CI и каталога.

15. Rollout waves

Начинать следует не с самых простых репозиториев, а с двух репрезентативных сложных cases — это раньше выявит недостатки модели.

flowchart LR
    W0["Wave 0: fixtures"] --> W1["Wave 1: LXD + Antivirus"]
    W1 --> G1{"Schema holds?"}
    G1 -->|нет| FIX["Исправить schema/runbook"]
    FIX --> W1
    G1 -->|да| W2["Wave 2: Docker, Network, Monitoring, Surveillance"]
    W2 --> W3["Wave 3: remaining Infra and Services"]
    W3 --> W4["Wave 4: software and project repositories"]

Для каждой wave:

  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.

skillProposal:
  name: repository-adoption
  purpose: Assess and prepare an existing repository for Repository Stewardship
  canonicalProcedure: docs/adoption-runbook.md
  defaultMode: plan
  allowedByDefault:
    - read repository metadata
    - classify repository
    - produce assessment
    - produce proposed diff
  approvalRequired:
    - write files
    - move or delete files
    - commit or push
    - access secrets
    - contact external systems
  forbidden:
    - duplicate repoctl logic
    - silently rewrite legacy KDB
    - execute discovered handlers during assessment

Предлагаемый вызов для Claude:

/repository-adoption C:\Users\alexander.baranov\Git\Infra\LXD --mode plan

До появления repoctl adopt skill выполняет runbook напрямую. После появления CLI он становится тонким wrapper: собирает недостающие решения пользователя, запускает команду и объясняет findings.

17. Что заимствовано из внешних практик

Практика Что используем
Backstage component registration сначала анализ существующего repository, затем review/import; descriptor добавляется PR
Backstage catalog graph repo-local YAML как source of truth; автоматическая классификация только начальная, metadata управляет человек
Renovate onboarding onboarding PR является безопасным gate; до merge другие изменения не выполняются
Copier updates template lineage, сохранённые answers, versioned update и явная обработка conflicts
OpenRewrite dry run recipe discovery, dry-run patch, review перед применением и возможность CI gate
GitHub organization rulesets rollout waves можно выбирать по repository properties, а enforcement включать после пилота

Вывод из сравнения: adoption должен быть не генератором файлов, а повторяемым конвейером discover → assess → plan → review → apply → verify, где до review нет записи, а полезное содержимое репозитория не становится собственностью шаблона.

18. Definition of done

Repository считается adopted, когда:

  • существует валидный ops/contract.yaml;
  • тип, owner, lifecycle и content roots подтверждены;
  • агент находит authoritative result paths без полного обхода дерева;
  • intent получает небольшой релевантный KDB context;
  • legacy KDB и domain content сохранены;
  • CLAUDE.md остаётся основной Claude-точкой входа;
  • portable instructions доступны через AGENTS.md, без import cycle;
  • contract виден в производном catalog;
  • unresolved warnings перечислены, имеют owner или осознанно deferred;
  • diff и validation evidence доступны для review.

L2 operations, нормализация дерева, замена credentials и исправление найденных domain problems являются отдельными follow-up changes, а не скрытой частью adoption.