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>
737 lines
41 KiB
Markdown
737 lines
41 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 выглядит полнее. Когда 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 по умолчанию.
|
||
|
||
```yaml
|
||
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`:
|
||
|
||
```yaml
|
||
acknowledgedFindings:
|
||
- code: ADOPT_SECRET_CONTENT_VERIFIED
|
||
path: airflow/.env
|
||
reason: rotation scheduled, tracked separately
|
||
```
|
||
|
||
Acknowledgement входит в plan, а значит в `planHash`, а значит в предмет approval: принять находку молча нельзя, и принятая находка не исчезает — `verify` возвращает её в `unresolvedFindings`.
|
||
|
||
```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_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 — это раньше выявит недостатки модели.
|
||
|
||
```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.
|