diff --git a/docs/PLAN.md b/docs/PLAN.md index 987f089..2203f27 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -107,9 +107,10 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify - Init/adoption tests подтверждают отсутствие записей до approval, отказ при неверном hash или изменившемся baseline и отсутствие commit/push. - LXD fixture сохраняет `profiles-source/`, `profiles/` и root `kdb.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. -- Реальные `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. ## Зафиксированные ограничения diff --git a/docs/adoption-runbook.md b/docs/adoption-runbook.md index 23914bb..8281ca4 100644 --- a/docs/adoption-runbook.md +++ b/docs/adoption-runbook.md @@ -103,11 +103,15 @@ adoptionModes: ```text 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 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. Входные данные Минимально необходимы: @@ -360,6 +364,10 @@ Plan MUST содержать rendered file contents или exact patch для к | legacy/custom KDB уже занимает `kdb/kdb.yaml` | создать `ops/knowledge.yaml` и указать его в contract | | несколько 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. ```yaml @@ -395,12 +403,12 @@ spec: |---|---| | оба отсутствуют | создать короткий `AGENTS.md` и импортирующий его `CLAUDE.md` | | только `AGENTS.md` | создать короткий `CLAUDE.md` с импортом | -| только `CLAUDE.md` | сохранить; предложить минимальный portable `AGENTS.md` | +| только `CLAUDE.md` | сохранить содержимое, добавить managed block с pointer; создать минимальный portable `AGENTS.md` | | оба есть и согласованы | сохранить, добавить только contract pointer при необходимости | | `AGENTS.md` ссылается на `CLAUDE.md` | не создавать обратный импорт; зарегистрировать legacy direction warning | | файлы противоречат друг другу | остановить автоматическую консолидацию и запросить owner decision | -Изменение shared entrypoint SHOULD выполняться через ограниченный managed block с markers, а не заменой всего файла. +Изменение shared entrypoint MUST выполняться через ограниченный managed block с markers `` и ``, а не заменой всего файла. Блок вставляется под первым заголовком первого уровня, чтобы pointer оказался выше основного текста. Повторный `plan` на уже пропатченном файле даёт `preserve`, поэтому adoption идемпотентна. Несогласованные или дублирующиеся markers — в файле или во вставляемом блоке — являются ошибкой `ADOPT_MANAGED_BLOCK_MALFORMED`, а не поводом угадывать границу. ### 11.3. Existing skills and handlers @@ -419,6 +427,8 @@ spec: ### 11.5. Normalization recipe `documents-to-content-root` +> **Не реализовано на L1.** `--strategy normalize` и `--recipe` не предлагаются CLI: пока нет canonical handler и validation path, объявлять операцию существующей нельзя. Раздел описывает целевое поведение, а не доступную команду. + Эта recipe MAY использоваться только по явному запросу владельца. Она не является частью default overlay. ```yaml @@ -507,19 +517,25 @@ 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 не перепутаны; -- legacy files byte-identical, если plan обещал `preserve`; - old paths из rename map больше не используются в active references; - все new paths из rename map существуют; -- diff ограничен approved paths; - catalog rebuild детерминирован; - external state не изменялся. @@ -556,6 +572,7 @@ findingCodes: ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning ADOPT_ENTRYPOINT_CONFLICT: blocker ADOPT_SECRET_TRACKED: blocker + ADOPT_SECRET_SHAPED_UNTRACKED: info ADOPT_SOURCE_MIRROR_AMBIGUOUS: confirmation-required ADOPT_BASELINE_CHANGED: blocker ADOPT_EXTERNAL_WRITE_DETECTED: blocker @@ -563,8 +580,19 @@ findingCodes: 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_PRESERVED_MODIFIED: blocker + ADOPT_DIFF_OUTSIDE_PLAN: warning + ADOPT_REPORT_UNSCOPED: warning + APPROVAL_FAILED: blocker ``` +`ADOPT_SECRET_TRACKED` относится только к **tracked** путям. Untracked путь с secret-shaped именем получает отдельный `ADOPT_SECRET_SHAPED_UNTRACKED`, а путь, который репозиторий явно игнорирует, не сообщается вовсе: blocker-код, срабатывающий на игнорируемых файлах, приучает игнорировать blocker. + +`ADOPT_WORKTREE_DIRTY` на этапе `assess` остаётся warning и не мешает планированию. На этапе `apply` он становится blocker, но только когда грязный путь входит в число тех, которые план записывает: незакоммиченная работа владельца в стороне от плана — не препятствие. + Коды стабильнее текстов и пригодны для CLI, CI и каталога. ## 15. Rollout waves