Files
repoctl/docs/adoption-runbook.md
T
Alexander BaranovandClaude Opus 5 1ab02a257c fix(adopt,init): decide by evidence, refuse instead of defaulting
Running a full assess -> plan -> apply -> verify against Infra/LXD and
Infra/Docker in throwaway worktrees, and a bootstrap into a scratch
directory, surfaced the same two mistakes repeated across both commands:
a shape was read where evidence was available, and a missing answer became
a silent default rather than a refusal.

adopt:

- classify secret-shaped paths by content, not by filename. A live
  credential blocks; a file tracked against the repository's own ignore
  rules and a name-only match are warnings; findings name keys, never
  values. In Infra/Docker this turned 14 false blockers into 2 true ones
  and surfaced 14 files committed despite `**/.env`.
- carry assess findings into the plan and refuse while an error-severity
  finding is unresolved. An owner may accept one through
  `acknowledgedFindings` with a reason; the acknowledgement enters the
  plan and therefore planHash, so approval covers it.
- derive metadata.name from the git remote instead of the clone directory,
  and refuse to plan without a confirmed owner (runbook section 9).
- propose content roots from the whole content vocabulary rather than the
  winning type's markers, and recognise N sibling directories sharing a
  marker file as one file-set root with a selector, as runbook 7.2 already
  specified. Authority defaulted rather than derived now asks.

init: apply the guards adopt already had. Answers are validated against
the vocabularies that already existed in constants (name, type, lifecycle,
access) so init can no longer create a repository that fails its own
validate; owners are required; a directory that already holds the planned
paths is refused at plan time and pointed at adopt; and every path from a
plan is confined before the first byte is written -- init wrote outside
the repository from an edited plan.

validate: mask fenced blocks and inline code spans before scanning for
Markdown links. A PowerShell snippet in Infra/Docker's CLAUDE.md parsed as
a link and kept validate red for a reason unrelated to the repository.

paths: allow "." as a whole content-root path, never as a segment, so the
file-set root runbook 7.2 describes can be declared.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 18:10:59 +03:00

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

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

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 выглядит полнее. Когда authority выбрана по умолчанию словаря, а не выведена из пары generatedFrom, assess помечает корень ADOPT_SOURCE_MIRROR_AMBIGUOUS и спрашивает владельца.

Content roots ищутся по всему словарю содержимого, а не только по маркерам предложенного type: docs/ числится evidence для project, и привязка поиска к победившему типу означала, что в infrastructure-репозитории он не объявлялся никогда. Type отвечает на вопрос «для чего репозиторий», content roots — «что в нём лежит».

Репозиторий из однотипных каталогов (стек на каталог) не имеет одного каталога, на который можно показать, а перечисление двадцати описывает раскладку вместо содержимого. Когда не менее трёх каталогов первого уровня несут общий маркерный файл (compose.y*ml, docker-compose.y*ml, Chart.yaml, main.tf, Dockerfile), объявляется один file-set корень с path: . и селектором — форма docker-stacks из примера выше. path: . допустим только как целый путь content root и никогда как write target.

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.

Содержимое secret-shaped файла читать разрешено — именно чтение отличает credential от документа о credentials, — но наружу выходят только имена ключей. Значения не попадают ни в findings, ни в логи, ни в assessment.

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
  identity:
    name: optools-lxd
    source: git-remote
  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 без отдельного диалога.

Граница подтверждения — не рекомендация. plan MUST отказываться строиться без подтверждённого owner (ADOPT_OWNER_UNKNOWN): контракт с owners: [] выглядит подтверждённым, хотя на вопрос никто не ответил.

Имя репозитория выводится из URL remote — последние два сегмента пути, приведённые к metadata.name (.../OpTools/LXD.git → optools-lxd). Каталог клона именем не является: два клона одного репозитория дали бы разные ответы, а worktree — третий. При отсутствии remote assess берёт имя каталога и помечает это ADOPT_NAME_INFERRED.

10. Phase 4 — adoption plan

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

Plan MUST переносить findings из assessment в поле findings и MUST отказываться строиться, пока остаётся хотя бы одна неразрешённая находка severity error (ADOPT_ASSESS_BLOCKERS_UNRESOLVED). Иначе единственный жёсткий результат assessment теряется на следующем шаге, а apply и verify возвращают success поверх репозитория, о котором assess сказал «блокер».

Владелец может принять конкретную находку, перечислив её в acknowledgedFindings с обязательным reason:

acknowledgedFindings:
  - code: ADOPT_SECRET_CONTENT_VERIFIED
    path: airflow/.env
    reason: rotation scheduled, tracked separately

Acknowledgement входит в plan, а значит в planHash, а значит в предмет approval: принять находку молча нельзя, и принятая находка не исчезает — verify возвращает её в unresolvedFindings.

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.

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.

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

Выполняются на 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 не изменялся.

Результат:

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_CONTENT_VERIFIED: blocker
  ADOPT_SECRET_IGNORED_BUT_TRACKED: warning
  ADOPT_SECRET_NAME_SHAPED: warning
  ADOPT_SECRET_SHAPED_UNTRACKED: info
  ADOPT_NAME_INFERRED: info
  ADOPT_ASSESS_BLOCKERS_UNRESOLVED: blocker
  ADOPT_ACKNOWLEDGEMENT_INCOMPLETE: 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
  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

Secret-shaped путь классифицируется по тому, что о нём действительно известно, а не по имени файла. Один blocker на совпадение имени давал в реальном репозитории 14 ложных находок из 16 и приучал пропускать все шестнадцать.

Код Severity Что установлено
ADOPT_SECRET_CONTENT_VERIFIED blocker в содержимом есть присваивание credential-ключа с реальным значением либо PEM private key block
ADOPT_SECRET_IGNORED_BUT_TRACKED warning путь отслеживается вопреки собственным ignore-правилам репозитория
ADOPT_SECRET_NAME_SHAPED warning совпало только имя; содержимое credential не несёт
ADOPT_SECRET_SHAPED_UNTRACKED info untracked и неигнорируемый путь

Содержимое читается только чтобы отличить credential от документа о credentials, и наружу выходят имена ключей, никогда значения (см. 7.3). Значения вида <SECRET:name>, ${VAR}, {{ var }}, changeme и подобные плейсхолдеры credential не считаются. Путь, который репозиторий игнорирует и который не отслеживается, не сообщается вовсе.

ADOPT_WORKTREE_DIRTY на этапе assess остаётся warning и не мешает планированию. На этапе apply он становится 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.