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>
This commit is contained in:
co-authored by
Claude Opus 5
parent
693211cee9
commit
1ab02a257c
+12
-4
@@ -38,10 +38,13 @@ repoctl describe --repo NAME|PATH [--root PATH ...]
|
||||
repoctl context --repo NAME|PATH --intent INTENT
|
||||
[--include-related] [--materialize]
|
||||
[--budget-bytes N] [--strict]
|
||||
repoctl init --repo PATH [--answers FILE] [--git-init|--no-git-init]
|
||||
repoctl init --repo PATH --name NAME --type TYPE --owner NAME
|
||||
[--answers FILE] [--title T] [--lifecycle L]
|
||||
[--git-init|--no-git-init]
|
||||
repoctl init --repo PATH --apply --plan FILE --approve SHA256
|
||||
repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
||||
[--answers FILE] [--strategy overlay|normalize]
|
||||
[--answers FILE] [--owner NAME] [--type TYPE]
|
||||
[--strategy overlay|normalize]
|
||||
[--recipe ID] [--plan FILE] [--approve SHA256]
|
||||
```
|
||||
|
||||
@@ -56,6 +59,8 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
||||
- Budget считается в UTF-8 bytes только для materialized content. Элементы сортируются детерминированно; усечение всегда отражается warning и при `--strict` даёт exit `4`.
|
||||
- Для хешей ресурсов используется canonical JSON representation, а не платформенные окончания строк. Время передаётся через clock abstraction, чтобы тестовые результаты были воспроизводимыми.
|
||||
|
||||
`init` проверяет ответы до сборки плана (`name` против `ID_PATTERN`, type/lifecycle/access против enum, обязательный owner), отказывается планировать в каталог, где уже лежит любой из создаваемых путей, и confine'ит каждый путь плана при записи. Отказы — конверты с кодами `INIT_*`, а не строки в stderr.
|
||||
|
||||
`init`:
|
||||
|
||||
- собирает ответы через CLI или YAML answers file; CLI имеет приоритет;
|
||||
@@ -75,7 +80,10 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
||||
- для legacy root `kdb.yaml` предлагает небольшой `kdb/kdb.yaml` adapter;
|
||||
- если legacy KDB уже занимает `kdb/kdb.yaml`, предлагает `ops/knowledge.yaml`;
|
||||
- существующие skills, handlers, KDB и agent instructions не переписывает;
|
||||
- tracked secret является blocker; untracked secret-shaped paths показываются path-only без содержимого;
|
||||
- secret-shaped путь классифицируется по содержимому: живой credential — blocker, tracked вопреки ignore-правилам и совпадение только по имени — warnings, untracked — info; наружу выходят имена ключей, не значения;
|
||||
- `plan` требует подтверждённого owner и отказывается строиться при неразрешённой находке severity `error`; принятие находки явное, с причиной, и входит в `planHash`;
|
||||
- имя репозитория выводится из remote, а не из имени каталога клона;
|
||||
- content roots предлагаются по всему словарю содержимого; репозиторий из однотипных каталогов объявляется одним `file-set` корнем с селектором;
|
||||
- `documents-to-content-root` выполняется только как явно выбранная normalization recipe с rename map, conservative Markdown/frontmatter/YAML rewrites и collision checks;
|
||||
- apply повторно проверяет baseline и plan hash, пишет только перечисленные paths, использует временные файлы и восстанавливает исходное состояние при локальной ошибке;
|
||||
- никогда не делает commit, push, clone или external operation.
|
||||
@@ -109,7 +117,7 @@ repoctl adopt --repo PATH --mode assess|plan|apply|verify
|
||||
- Antivirus fixture сохраняет custom `kdb/kdb.yaml` и предлагает `ops/knowledge.yaml`.
|
||||
- Normalization tests отложены вместе с самой normalization: `--strategy normalize` и recipes не реализованы и не предлагаются CLI.
|
||||
- Самопроверка: `repoctl validate --repo .`, unit/integration tests, Ruff, strict typing и сборка wheel с проверкой наличия schemas/templates.
|
||||
- `Infra/LXD` используется только для read-only `assess` и `plan`; Git status до и после должен совпасть.
|
||||
- `Infra/LXD` и `Infra/Docker` используются только для read-only `assess` и `plan`, либо для полного цикла в одноразовом `git worktree`; Git status рабочего дерева до и после должен совпасть.
|
||||
- `Services/Antivirus` — пилот Wave 1, adopted по решению владельца. `apply` к нему выполняется осознанно: через утверждённый `planHash`, с предварительным прогоном на копии и последующим `verify --plan`. Остальные реальные репозитории остаются read-only до расширения wave.
|
||||
|
||||
## Зафиксированные ограничения
|
||||
|
||||
@@ -219,7 +219,11 @@ contentRoots:
|
||||
selector: "*/compose.y*ml"
|
||||
```
|
||||
|
||||
Нельзя объявлять mirror как source только потому, что его YAML выглядит полнее.
|
||||
Нельзя объявлять 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
|
||||
|
||||
@@ -234,6 +238,8 @@ contentRoots:
|
||||
- freshness signals;
|
||||
- наличие потенциальных secret-shaped paths или keys без вывода values.
|
||||
|
||||
Содержимое secret-shaped файла читать разрешено — именно чтение отличает credential от документа о credentials, — но наружу выходят только имена ключей. Значения не попадают ни в findings, ни в логи, ни в assessment.
|
||||
|
||||
### 7.4. Найти agent entrypoints и automation
|
||||
|
||||
Определить:
|
||||
@@ -267,6 +273,9 @@ runbookOutput:
|
||||
path: Infra/LXD
|
||||
baselineRevision: 0123456789abcdef
|
||||
dirty: false
|
||||
identity:
|
||||
name: optools-lxd
|
||||
source: git-remote
|
||||
classification:
|
||||
proposedType: infrastructure-config
|
||||
confidence: high
|
||||
@@ -311,10 +320,27 @@ Assessment MUST distinguish `detected`, `inferred` and `confirmed` values.
|
||||
|
||||
Остальные безопасные 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
|
||||
@@ -578,8 +604,13 @@ findingCodes:
|
||||
ADOPT_KDB_CANONICAL_PATH_OCCUPIED: warning
|
||||
ADOPT_ENTRYPOINT_DIRECTION_LEGACY: warning
|
||||
ADOPT_ENTRYPOINT_CONFLICT: blocker
|
||||
ADOPT_SECRET_TRACKED: 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
|
||||
@@ -597,7 +628,16 @@ findingCodes:
|
||||
APPROVAL_FAILED: blocker
|
||||
```
|
||||
|
||||
`ADOPT_SECRET_TRACKED` относится только к **tracked** путям. Untracked путь с secret-shaped именем получает отдельный `ADOPT_SECRET_SHAPED_UNTRACKED`, а путь, который репозиторий явно игнорирует, не сообщается вовсе: blocker-код, срабатывающий на игнорируемых файлах, приучает игнорировать 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, но только когда грязный путь входит в число тех, которые план записывает: незакоммиченная работа владельца в стороне от плана — не препятствие.
|
||||
|
||||
|
||||
@@ -819,6 +819,10 @@ Bootstrap предлагает, но не навязывает:
|
||||
|
||||
Для существующего репозитория используется другая операция — `repoctl adopt`. Она не раскладывает старый repository как новый шаблон, а сначала картографирует уже существующие источники истины, agent instructions, KDB и штатные места результата.
|
||||
|
||||
Перед планом adoption обязана получить ответ на то, что нельзя вывести: кто владелец. Пустой список владельцев в контракте выглядит как подтверждённый ответ, хотя никто не отвечал, поэтому `plan` без владельца просто не строится. Имя репозитория при этом берётся из remote, а не из имени каталога, в который его склонировали.
|
||||
|
||||
Найденные секреты различаются по тому, что о них известно. Файл с живым паролем внутри — блокер: план не построится, пока владелец либо не уберёт секрет, либо не примет находку явно и с причиной. Файл, чьё имя лишь похоже на секрет (например, документ `SECRETS.md` про конвенцию плейсхолдеров), и файл, закоммиченный вопреки собственному `.gitignore`, — предупреждения. Содержимое при этом читается только для этой классификации, и наружу выходят имена ключей, но никогда значения.
|
||||
|
||||
По умолчанию adoption добавляет overlay и ничего не переносит. Если владелец отдельно просит упорядочить дерево, используется именованная normalization recipe. Например, `documents-to-content-root` оставляет в корне `README.md`, `AGENTS.md` и `CLAUDE.md`, переносит только подтверждённые длинные документы и одновременно переписывает contract, KDB, frontmatter и Markdown links.
|
||||
|
||||
```mermaid
|
||||
|
||||
+25
-2
@@ -105,6 +105,16 @@ repoctl context --repo . --intent domain.action --output json
|
||||
repoctl init --repo ../new-repo --name new-repo --type project --owner team-name --output json > plan.json
|
||||
```
|
||||
|
||||
Ответы проверяются до сборки плана, чтобы `init` не мог создать репозиторий, который не проходит собственный `validate`:
|
||||
|
||||
| Код | Когда |
|
||||
|---|---|
|
||||
| `INIT_ANSWERS_INCOMPLETE` | нет `--name` или `--type` |
|
||||
| `INIT_NAME_INVALID` | имя не подходит под `^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`; в сообщении есть готовая замена (`Services/Mail` → `services-mail`) |
|
||||
| `INIT_TYPE_UNKNOWN`, `INIT_LIFECYCLE_UNKNOWN`, `INIT_ACCESS_UNKNOWN` | значение вне enum схемы |
|
||||
| `INIT_OWNER_UNKNOWN` | владелец не подтверждён — та же граница, что у `adopt` |
|
||||
| `INIT_PATH_COLLISION` | каталог уже содержит один из создаваемых путей; для существующего репозитория нужен `adopt`, а не `init` |
|
||||
|
||||
В ответе — полный список файлов, которые будут созданы (`ops/contract.yaml`, `kdb/kdb.yaml`, `AGENTS.md`, `CLAUDE.md`, `.claude/skills/*`, и т.д.) и `planHash`. Прочитайте план, убедитесь, что он ожидаем.
|
||||
|
||||
```bash
|
||||
@@ -120,11 +130,23 @@ repoctl init --repo ../new-repo --apply --plan plan.json --approve sha256:<planH
|
||||
|
||||
```bash
|
||||
repoctl adopt --repo ../legacy-repo --mode assess --output json # инвентаризация, ничего не пишет
|
||||
repoctl adopt --repo ../legacy-repo --mode plan --output json # предлагаемый diff + planHash, ничего не пишет
|
||||
repoctl adopt --repo ../legacy-repo --mode plan --owner infra --output json # предлагаемый diff + planHash, ничего не пишет
|
||||
repoctl adopt --repo ../legacy-repo --mode apply --plan plan.json --approve sha256:<planHash> --output json
|
||||
repoctl adopt --repo ../legacy-repo --mode verify --output json # отчёт о совместимости после apply
|
||||
```
|
||||
|
||||
`plan` требует подтверждённого владельца — `--owner` (можно повторять) либо `owners:` в `--answers`; без него он отказывается строиться, а не выпускает контракт с пустым `owners`. Имя репозитория берётся из URL remote (последние два сегмента: `.../OpTools/LXD.git` → `optools-lxd`), либо задаётся `name:` в файле ответов.
|
||||
|
||||
`plan` также отказывается строиться, пока `assess` оставил находку severity `error` — например, файл с живым credential в git. Принять такую находку осознанно можно в файле ответов; `reason` обязателен, а сам acknowledgement входит в `planHash`:
|
||||
|
||||
```yaml
|
||||
owners: [infrastructure]
|
||||
acknowledgedFindings:
|
||||
- code: ADOPT_SECRET_CONTENT_VERIFIED
|
||||
path: airflow/.env
|
||||
reason: rotation scheduled, tracked separately
|
||||
```
|
||||
|
||||
По умолчанию используется стратегия `overlay`: existing domain-native layout (например, `profiles-source/`, существующий `kdb.yaml` в корне) не перемещается и не переписывается — поверх него добавляется только недостающая метадата Stewardship. Если в репозитории уже занят путь `kdb/kdb.yaml`, `adopt` предложит `ops/knowledge.yaml` вместо конфликта. `apply` никогда не делает `git commit`, `push` или `clone`.
|
||||
|
||||
## Коды возврата
|
||||
@@ -145,5 +167,6 @@ repoctl adopt --repo ../legacy-repo --mode verify --output json # отчёт
|
||||
- **`ERROR: No .git ancestor found`** — команда запущена вне git-репозитория и `--repo` не указан явно; передайте `--repo <путь>` или запустите `git init` в целевом каталоге.
|
||||
- **`APPROVAL_FAILED` при `init --apply`/`adopt --mode apply`** — переданный `--approve` не совпадает с `planHash` в файле плана; пересчитайте план заново (сравнение файла плана и `planHash` в нём — самопроверка от случайной правки плана вручную).
|
||||
- **`ADOPT_BASELINE_CHANGED`** — репозиторий изменился между `--mode plan` и `--mode apply` (кто-то создал файл из плана вручную); постройте план заново.
|
||||
- **`ADOPT_PATH_COLLISION` / `init` отказывается писать** — план целится в уже существующий файл; `repoctl` намеренно не перезаписывает существующее содержимое — удалите или переименуйте конфликтующий файл вручную и постройте план заново.
|
||||
- **`ADOPT_PATH_COLLISION` / `init` отказывается писать** — план целится в уже существующий файл; `repoctl` намеренно не перезаписывает существующее содержимое — удалите или переименуйте конфликтующий файл вручную и постройте план заново. `INIT_PATH_COLLISION` на этапе плана означает, что каталог уже является репозиторием: используйте `adopt`.
|
||||
- **`INIT_PATH_OUTSIDE_REPOSITORY`** — путь в файле плана ведёт наружу репозитория. План — обычный файл; если он был отредактирован вручную или перенесён между машинами, постройте его заново вместо правки.
|
||||
- **Windows: кириллица или спецсимволы искажены в выводе** — используйте актуальную версию `repoctl`; вывод принудительно кодируется в UTF-8 независимо от кодовой страницы консоли.
|
||||
|
||||
+12
-1
@@ -923,6 +923,10 @@ MCP является transport/discovery layer и MUST NOT становитьс
|
||||
|
||||
### 18.1. `repoctl init`
|
||||
|
||||
`init` — единственный путь, где инструмент контролирует каждый байт результата, поэтому созданный им репозиторий MUST проходить `repoctl validate` по построению. Ответы MUST проверяться до сборки плана: `metadata.name` против `ID_PATTERN`, type против набора типов, lifecycle и access против своих enum. Owner MUST быть подтверждён — та же граница, что и в `adopt`: контракт не знает, какая команда его создала.
|
||||
|
||||
`init` MUST отказываться планировать в каталог, где уже лежит любой из создаваемых им путей, и указывать на `adopt` как на правильную операцию. `apply` MUST confine каждый путь из плана внутрь репозитория: план — обычный файл, который можно отредактировать вручную.
|
||||
|
||||
MVP bootstrap SHOULD:
|
||||
|
||||
1. определить repository type;
|
||||
@@ -951,6 +955,9 @@ Adoption MUST:
|
||||
- создавать совместимый KDB index рядом, если канонический путь занят legacy-форматом;
|
||||
- показывать полный diff до записи;
|
||||
- разделять автоматически найденные факты и подтверждённые владельцем решения;
|
||||
- отказываться строить plan без подтверждённого owner и выводить `metadata.name` из remote, а не из имени каталога клона;
|
||||
- переносить findings из assessment в plan и отказываться строить plan, пока остаётся неразрешённая находка severity `error`; принятие такой находки MUST быть явным, с указанием причины, и входить в `planHash`;
|
||||
- классифицировать secret-shaped пути по содержимому, а не только по имени, и не выводить значения — только имена ключей;
|
||||
- допускать остановку после `assess` или `plan` без изменения репозитория;
|
||||
- при `overlay` изменять только repository-local metadata после явного подтверждения;
|
||||
- при `normalize` изменять только paths из подтверждённой recipe и обновлять все contract/KDB/Markdown references атомарно;
|
||||
@@ -1159,7 +1166,11 @@ MVP считается готовым, когда:
|
||||
17. adoption LXD сохраняет `profiles-source/`, `profiles/` и root `kdb.yaml` на месте;
|
||||
18. adoption Antivirus не перезаписывает существующий custom `kdb/kdb.yaml`.
|
||||
19. `documents-to-content-root` не перемещает `README.md`, `AGENTS.md`, `CLAUDE.md`, license и community files;
|
||||
20. normalization plan включает rename map и обновляет contract, KDB, frontmatter и Markdown links до записи.
|
||||
20. normalization plan включает rename map и обновляет contract, KDB, frontmatter и Markdown links до записи;
|
||||
21. `adopt --mode plan` отказывается строиться без подтверждённого owner и при неразрешённой находке severity `error`;
|
||||
22. содержимое secret-shaped файла может читаться для классификации, но значения не попадают ни в один вывод;
|
||||
23. content roots предлагаются по всему словарю содержимого, а не только по маркерам предложенного type;
|
||||
24. репозиторий из однотипных каталогов объявляется одним `file-set` корнем с селектором, а не N директориями.
|
||||
|
||||
## 25. Сквозной пример contract: infrastructure provider
|
||||
|
||||
|
||||
Reference in New Issue
Block a user