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
@@ -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, но только когда грязный путь входит в число тех, которые план записывает: незакоммиченная работа владельца в стороне от плана — не препятствие.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user