docs: align the runbook with what adoption actually does
The tables in sections 11.1 and 11.2 were right and the code was wrong, so most of this is recording how a row is decided rather than changing the rule: format comes from validating content against the KnowledgeBase schema, never from the path a file happens to occupy. Section 13 promised thirteen verify checks and ran none of the specific ones. Rather than let the list keep implying coverage that does not exist, it now separates what L1 checks from what waits on normalization and L3, and states plainly that an unscoped report proves nothing. - document the managed-block markers, insertion point and idempotence - mark normalization and its recipes as not implemented, matching the CLI - record that migrate does not exist, which is why post-adoption edits to a contract currently fall outside plan/approve - add the finding codes introduced with the safety and verify work, and explain why a tracked secret and an ignored one are no longer the same code - PLAN.md: Antivirus is a Wave 1 pilot the owner adopts deliberately; LXD stays read-only. Normalization test row follows the feature into deferral Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
e5a42fa446
commit
1974155281
+3
-2
@@ -107,9 +107,10 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
|||||||
- Init/adoption tests подтверждают отсутствие записей до approval, отказ при неверном hash или изменившемся baseline и отсутствие commit/push.
|
- Init/adoption tests подтверждают отсутствие записей до approval, отказ при неверном hash или изменившемся baseline и отсутствие commit/push.
|
||||||
- LXD fixture сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml`.
|
- LXD fixture сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml`.
|
||||||
- Antivirus fixture сохраняет custom `kdb/kdb.yaml` и предлагает `ops/knowledge.yaml`.
|
- Antivirus fixture сохраняет custom `kdb/kdb.yaml` и предлагает `ops/knowledge.yaml`.
|
||||||
- Normalization tests покрывают exclusions, case-insensitive collisions, reference rewrites и rollback.
|
- Normalization tests отложены вместе с самой normalization: `--strategy normalize` и recipes не реализованы и не предлагаются CLI.
|
||||||
- Самопроверка: `repoctl validate --repo .`, unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
|
- Самопроверка: `repoctl validate --repo .`, unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
|
||||||
- Реальные `Infra/LXD` и `Services/Antivirus` используются только для read-only `assess` и `plan`; Git status до и после должен совпасть. Никакие планы к ним не применяются.
|
- `Infra/LXD` используется только для read-only `assess` и `plan`; Git status до и после должен совпасть.
|
||||||
|
- `Services/Antivirus` — пилот Wave 1, adopted по решению владельца. `apply` к нему выполняется осознанно: через утверждённый `planHash`, с предварительным прогоном на копии и последующим `verify --plan`. Остальные реальные репозитории остаются read-only до расширения wave.
|
||||||
|
|
||||||
## Зафиксированные ограничения
|
## Зафиксированные ограничения
|
||||||
|
|
||||||
|
|||||||
@@ -103,11 +103,15 @@ adoptionModes:
|
|||||||
|
|
||||||
```text
|
```text
|
||||||
repoctl adopt --repo PATH --mode assess --output yaml
|
repoctl adopt --repo PATH --mode assess --output yaml
|
||||||
repoctl adopt --repo PATH --mode plan --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 apply --plan PLAN --approve PLAN_HASH
|
||||||
repoctl adopt --repo PATH --mode verify --output yaml
|
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. Входные данные
|
## 5. Входные данные
|
||||||
|
|
||||||
Минимально необходимы:
|
Минимально необходимы:
|
||||||
@@ -360,6 +364,10 @@ Plan MUST содержать rendered file contents или exact patch для к
|
|||||||
| legacy/custom KDB уже занимает `kdb/kdb.yaml` | создать `ops/knowledge.yaml` и указать его в contract |
|
| legacy/custom KDB уже занимает `kdb/kdb.yaml` | создать `ops/knowledge.yaml` и указать его в contract |
|
||||||
| несколько knowledge sources | index с topics/documents и явным authority |
|
| несколько knowledge sources | index с topics/documents и явным authority |
|
||||||
|
|
||||||
|
Выбор между второй и четвёртой строкой определяется **валидацией содержимого** против schema `KnowledgeBase`, а не расположением файла. Файл не является conformant KDB только потому, что лежит в каноническом path: ранняя реализация делала именно это допущение и в результате указывала contract на файл, не проходящий schema, что обнаруживалось только на `verify`.
|
||||||
|
|
||||||
|
Сгенерированный index создаётся с пустым `topics`. Какие секции legacy source заслуживают отдельного intent — решение владельца, а не вывод инструмента: adoption регистрирует документ и оставляет routing на осознанный следующий шаг.
|
||||||
|
|
||||||
Compatibility index MAY ссылаться на legacy YAML sections через `Topic.data.x-selector`, но не должен копировать весь legacy source.
|
Compatibility index MAY ссылаться на legacy YAML sections через `Topic.data.x-selector`, но не должен копировать весь legacy source.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
@@ -395,12 +403,12 @@ spec:
|
|||||||
|---|---|
|
|---|---|
|
||||||
| оба отсутствуют | создать короткий `AGENTS.md` и импортирующий его `CLAUDE.md` |
|
| оба отсутствуют | создать короткий `AGENTS.md` и импортирующий его `CLAUDE.md` |
|
||||||
| только `AGENTS.md` | создать короткий `CLAUDE.md` с импортом |
|
| только `AGENTS.md` | создать короткий `CLAUDE.md` с импортом |
|
||||||
| только `CLAUDE.md` | сохранить; предложить минимальный portable `AGENTS.md` |
|
| только `CLAUDE.md` | сохранить содержимое, добавить managed block с pointer; создать минимальный portable `AGENTS.md` |
|
||||||
| оба есть и согласованы | сохранить, добавить только contract pointer при необходимости |
|
| оба есть и согласованы | сохранить, добавить только contract pointer при необходимости |
|
||||||
| `AGENTS.md` ссылается на `CLAUDE.md` | не создавать обратный импорт; зарегистрировать legacy direction warning |
|
| `AGENTS.md` ссылается на `CLAUDE.md` | не создавать обратный импорт; зарегистрировать legacy direction warning |
|
||||||
| файлы противоречат друг другу | остановить автоматическую консолидацию и запросить owner decision |
|
| файлы противоречат друг другу | остановить автоматическую консолидацию и запросить owner decision |
|
||||||
|
|
||||||
Изменение shared entrypoint SHOULD выполняться через ограниченный managed block с markers, а не заменой всего файла.
|
Изменение 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
|
### 11.3. Existing skills and handlers
|
||||||
|
|
||||||
@@ -419,6 +427,8 @@ spec:
|
|||||||
|
|
||||||
### 11.5. Normalization recipe `documents-to-content-root`
|
### 11.5. Normalization recipe `documents-to-content-root`
|
||||||
|
|
||||||
|
> **Не реализовано на L1.** `--strategy normalize` и `--recipe` не предлагаются CLI: пока нет canonical handler и validation path, объявлять операцию существующей нельзя. Раздел описывает целевое поведение, а не доступную команду.
|
||||||
|
|
||||||
Эта recipe MAY использоваться только по явному запросу владельца. Она не является частью default overlay.
|
Эта recipe MAY использоваться только по явному запросу владельца. Она не является частью default overlay.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
@@ -507,19 +517,25 @@ Apply не делает commit или push, если пользователь н
|
|||||||
|
|
||||||
## 13. Phase 6 — verify
|
## 13. Phase 6 — verify
|
||||||
|
|
||||||
Обязательные проверки:
|
Выполняются на L1 (`repoctl adopt --mode verify --plan <файл>`):
|
||||||
|
|
||||||
- YAML parse и schema validation;
|
- YAML parse и schema validation;
|
||||||
- repo-relative path confinement;
|
- repo-relative path confinement;
|
||||||
- существование всех content roots и documents;
|
- существование всех content roots и documents;
|
||||||
- отсутствие циклов entrypoint imports;
|
- отсутствие циклов 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;
|
- intent выбирает ожидаемые topics, но не весь KDB;
|
||||||
- selector находит ожидаемые domain artifacts;
|
- selector находит ожидаемые domain artifacts;
|
||||||
- source/mirror authority не перепутаны;
|
- source/mirror authority не перепутаны;
|
||||||
- legacy files byte-identical, если plan обещал `preserve`;
|
|
||||||
- old paths из rename map больше не используются в active references;
|
- old paths из rename map больше не используются в active references;
|
||||||
- все new paths из rename map существуют;
|
- все new paths из rename map существуют;
|
||||||
- diff ограничен approved paths;
|
|
||||||
- catalog rebuild детерминирован;
|
- catalog rebuild детерминирован;
|
||||||
- external state не изменялся.
|
- external state не изменялся.
|
||||||
|
|
||||||
@@ -556,6 +572,7 @@ findingCodes:
|
|||||||
ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
|
ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
|
||||||
ADOPT_ENTRYPOINT_CONFLICT: blocker
|
ADOPT_ENTRYPOINT_CONFLICT: blocker
|
||||||
ADOPT_SECRET_TRACKED: blocker
|
ADOPT_SECRET_TRACKED: blocker
|
||||||
|
ADOPT_SECRET_SHAPED_UNTRACKED: info
|
||||||
ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required
|
ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required
|
||||||
ADOPT_BASELINE_CHANGED: blocker
|
ADOPT_BASELINE_CHANGED: blocker
|
||||||
ADOPT_EXTERNAL_WRITE_DETECTED: blocker
|
ADOPT_EXTERNAL_WRITE_DETECTED: blocker
|
||||||
@@ -563,8 +580,19 @@ findingCodes:
|
|||||||
ADOPT_ROOT_DOCUMENT_CANDIDATE: info
|
ADOPT_ROOT_DOCUMENT_CANDIDATE: info
|
||||||
ADOPT_MOVE_COLLISION: blocker
|
ADOPT_MOVE_COLLISION: blocker
|
||||||
ADOPT_REFERENCE_REWRITE_INCOMPLETE: blocker
|
ADOPT_REFERENCE_REWRITE_INCOMPLETE: blocker
|
||||||
|
ADOPT_PATH_OUTSIDE_REPOSITORY: blocker
|
||||||
|
ADOPT_FORBIDDEN_PATH: blocker
|
||||||
|
ADOPT_MANAGED_BLOCK_MALFORMED: 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 и каталога.
|
Коды стабильнее текстов и пригодны для CLI, CI и каталога.
|
||||||
|
|
||||||
## 15. Rollout waves
|
## 15. Rollout waves
|
||||||
|
|||||||
Reference in New Issue
Block a user