Files
Alexander BaranovandClaude Opus 5 1ab02a257c 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>
2026-08-25 18:10:59 +03:00

939 lines
45 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
documentId: repository-stewardship-guide
documentVersion: 0.2.0
status: draft
normative: false
language: ru
machineSpecification: docs/specification.md
architectureSource: docs/research/infrastructure-operations-architecture-options.md
---
# Универсальная работа с репозиториями: руководство для человека
Модель называется **Repository Stewardship**: ответственное и долговременное ведение структуры, знаний, связей и способов работы репозитория. `repoctl` — её локальный командный интерфейс.
## 1. Коротко о результате
Каждый управляемый репозиторий получает:
1. короткий машиночитаемый паспорт — `ops/contract.yaml`;
2. индекс знаний — `kdb/kdb.yaml`;
3. явные указатели на места реального результата работы — `contentRoots`;
4. короткие точки входа `CLAUDE.md` и `AGENTS.md`;
5. при необходимости — собственные безопасные operations и handlers.
Общий инструмент `repoctl` умеет найти эти файлы, проверить их, построить каталог и передать агенту только контекст, необходимый для конкретной задачи.
Так получается «MCP-подобный» инструментарий без обязательного MCP server: репозитории уже предоставляют ресурсы, знания и операции через общий контракт, а CLI, Claude skills, другие агенты и будущий MCP становятся сменными интерфейсами.
Машинные поля и правила определены в [specification.md](specification.md). Этот документ объясняет ту же модель простым языком. Процедура подключения существующих репозиториев описана в [adoption-runbook.md](adoption-runbook.md). Исходные архитектурные варианты и исследование сохранены в [research/infrastructure-operations-architecture-options.md](research/infrastructure-operations-architecture-options.md).
## 2. Главные принципы
### 2.1. Репозиторий сам описывает себя
Центральная база не должна вручную хранить копии сведений обо всех репозиториях. Каждый repository contract находится рядом с материалами, которые он описывает. Центральный каталог можно полностью перестроить.
### 2.2. Одинаков интерфейс, а не физическое дерево
LXD profiles могут оставаться в `profiles-source/`, Docker stacks — в каталогах стеков, код — в `src/`, а проектные результаты — в `deliverables/`.
Контракт просто называет эти места и объясняет их роль. Агент больше не выясняет структуру заново, но репозитории не ломаются ради искусственной унификации.
### 2.3. Знание загружается по задаче
`CLAUDE.md` не превращается в энциклопедию. Пользовательская задача преобразуется в intent, например `container.deploy`. По intent выбираются только связанные темы KDB, документы, content roots и operations.
### 2.4. Потребитель формулирует потребность, провайдер реализует её
Antivirus знает, какой сервис ему нужен и как проверить его работу. LXD знает, как создать контейнер. Network знает, как предоставить сеть. Ни один из них не должен копировать authoritative configuration другого.
### 2.5. Сначала безопасная семантика, затем выполнение
Первая версия только обнаруживает, валидирует и выдаёт контекст. Затем добавляются единый handler protocol, Plan, approval, apply и evidence. MCP появляется последним как транспорт над уже проверенной моделью.
## 3. Общая архитектура
```mermaid
flowchart TB
U["Пользователь"] --> A["Claude или другой AI-агент"]
A --> E["CLAUDE.md / AGENTS.md / skill"]
E --> R["repoctl"]
R --> C["RepositoryContract"]
R --> K["KnowledgeBase"]
R --> G["Производный CatalogIndex"]
C --> CR["contentRoots"]
C --> O["operations"]
C --> REL["requirements / capabilities / bindings"]
K --> T["topics по intent"]
T --> D["Markdown и vendor sources"]
O -. "после L2" .-> H["Repo-local handlers"]
H -. "domain API/CLI" .-> X["LXD / Docker / AD / Network / Monitoring"]
R -. "после L3" .-> P["Plan / approval / RunEvidence"]
R -. "опционально" .-> M["MCP adapter"]
```
Важное разделение:
- contract и KDB принадлежат репозиторию;
- catalog и context bundle вычисляются `repoctl`;
- handler принадлежит своему техническому домену;
- skill и MCP только помогают вызвать тот же интерфейс.
## 4. Минимальная структура репозитория
```mermaid
flowchart LR
ROOT["repository root"] --> CONTRACT["ops/contract.yaml"]
ROOT --> KDB["kdb/kdb.yaml"]
ROOT --> AGENTS["AGENTS.md"]
ROOT --> CLAUDE["CLAUDE.md"]
ROOT --> DOCS["docs/"]
ROOT --> OPS["ops/"]
ROOT --> DOMAIN["domain-native content"]
OPS --> HANDLERS["handlers/ — после L2"]
OPS --> SCHEMAS["schemas/ — по необходимости"]
OPS --> RUNS["runs/ — локальные планы и evidence"]
DOMAIN --> EX1["profiles-source/"]
DOMAIN --> EX2["stacks/"]
DOMAIN --> EX3["src/"]
DOMAIN --> EX4["deliverables/"]
```
Обязательная часть проста:
- `ops/contract.yaml` — паспорт;
- `kdb/kdb.yaml` — индекс знаний;
- `AGENTS.md` — переносимые инструкции;
- `CLAUDE.md` — вход для основного агента Claude.
Остальные каталоги создаются только при реальной необходимости.
## 5. Четыре типа репозиториев
```mermaid
flowchart TB
R["Repository"] --> I["Infrastructure configuration"]
R --> S["Service configuration"]
R --> C["Software / code"]
R --> P["Project / non-code"]
I --> I1["desired state"]
I --> I2["inventory / profiles / stacks"]
I --> I3["observed state / evidence"]
S --> S1["service definition"]
S --> S2["policies / requirements"]
S --> S3["acceptance / runbooks"]
C --> C1["source"]
C --> C2["tests / build"]
C --> C3["packages / deployment"]
P --> P1["deliverables"]
P --> P2["sources / working"]
P --> P3["decisions / archive"]
```
| Тип | За что отвечает | Что особенно важно |
|---|---|---|
| Infrastructure configuration | контейнеры, сеть, серверы, платформенная конфигурация | разделить desired и observed state; иметь diff/plan/verify |
| Service configuration | продуктовая конфигурация и правила эксплуатации сервиса | владеть requirements и acceptance, не копировать provider configuration |
| Software/code | исходники, тесты, сборка и выпуск | следовать conventions своего ecosystem, явно отделить deployment artifacts |
| Project/non-code | документы, исследования, планы и результаты | явно назвать deliverables, sources и decisions |
Организационный путь, уровень доступа и lifecycle не определяют тип. Например, репозиторий в `Services/` может содержать software, а архивный инфраструктурный repository остаётся типом `infrastructure-config`.
## 6. Карта сущностей
```mermaid
erDiagram
REPOSITORY ||--|| REPOSITORY_CONTRACT : publishes
REPOSITORY ||--o| KNOWLEDGE_BASE : owns
REPOSITORY_CONTRACT ||--o{ CONTENT_ROOT : declares
REPOSITORY_CONTRACT ||--o{ OPERATION : exposes
REPOSITORY_CONTRACT ||--o{ CAPABILITY : provides
REPOSITORY_CONTRACT ||--o{ REQUIREMENT : requires
REPOSITORY_CONTRACT ||--o{ BINDING : records
KNOWLEDGE_BASE ||--o{ TOPIC : routes
KNOWLEDGE_BASE ||--o{ KNOWLEDGE_DOCUMENT : indexes
TOPIC }o--o{ KNOWLEDGE_DOCUMENT : selects
REQUIREMENT }o--o{ CAPABILITY : matches
BINDING }o--|| REQUIREMENT : fulfills
OPERATION ||--o| HANDLER : implemented_by
INTENT }o--o{ TOPIC : selects
INTENT }o--o{ OPERATION : selects
PLAN ||--o{ OPERATION : orders
RUN_EVIDENCE }o--|| PLAN : proves
```
Дальше сущности объясняются в том порядке, в котором они встречаются при работе.
## 7. Сущности: от входа в репозиторий до понимания задачи
### 7.1. Репозиторий
Отдельная область ответственности и отдельный источник истины.
Примеры:
- `Infra/LXD` отвечает за контейнеры и LXD profiles;
- `Services/Antivirus` отвечает за требования и правила приёмки антивируса;
- software repository отвечает за код;
- project repository отвечает за результаты проекта.
### 7.2. RepositoryContract
Короткий машиночитаемый паспорт репозитория в `ops/contract.yaml`.
Он отвечает на вопросы:
- что это за репозиторий;
- кто его владелец;
- где лежит результат работы;
- что он предоставляет и что требует;
- какие операции публично разрешены;
- где находится его KDB.
Контракт не заменяет документацию. Это оглавление, интерфейс и граница ответственности.
### 7.3. Metadata
Стабильное имя, отображаемое название, владельцы, labels и annotations.
Стабильное имя вроде `infra-lxd` важнее физического пути. Репозиторий можно переместить, не меняя ссылки в requirements и bindings.
### 7.4. Repository type
Один из четырёх функциональных типов. Он определяет хорошие практики организации, но не заставляет использовать одно дерево каталогов.
### 7.5. Lifecycle
Текущее состояние репозитория:
- `production`;
- `active`;
- `experimental`;
- `stub`;
- `archive`;
- `external`.
Lifecycle помогает агенту не принять эксперимент или архив за production source.
### 7.6. ContentRoot
Явный указатель на место, где лежит настоящий результат работы.
Content root имеет:
- стабильный ID;
- роль;
- путь;
- природу данных (`authority`);
- политику записи;
- при необходимости selector.
Например, `profiles-source/` может быть source, а `profiles/` — generated mirror. Оба содержат YAML, но обращаться с ними нужно по-разному.
### 7.7. Authority
Объясняет природу содержимого:
- `source` — первоисточник;
- `generated` — автоматически созданное;
- `observed` — полученное из runtime;
- `mirror` — копия другого источника;
- `evidence` — историческое доказательство.
## 8. Сущности: от пользовательского запроса до нужного знания
### 8.1. Intent
Краткое имя цели пользователя, а не техническая команда.
Например, запрос:
> Разверни новый контейнер LXD для антивируса.
преобразуется в intent:
```text
container.deploy
```
Intent помогает выбрать репозитории, темы KDB и операции. В нём нет hostname, пароля или shell-команды.
### 8.2. CatalogIndex
Производная телефонная книга репозиториев.
Она позволяет найти:
- какой repository предоставляет LXD containers;
- где находится Antivirus;
- какие requirements ещё не имеют bindings;
- какие repositories являются архивными.
Каталог можно удалить и пересобрать из contracts.
### 8.3. Entity и relation
Entity — объект каталога: repository, capability, requirement, binding или operation.
Relation — связь между объектами:
```text
Antivirus requires LXD container
LXD provides LXD container
Binding fulfills Antivirus requirement
```
Совокупность relations образует граф, по которому агент переходит между репозиториями без угадывания путей.
### 8.4. KnowledgeBase
Машиночитаемый индекс знаний в `kdb/kdb.yaml`.
KDB не обязана содержать весь текст. Она хранит:
- темы;
- соответствующие intents;
- машиночитаемые constraints и facts;
- ссылки на Markdown;
- сведения о vendor sources;
- provenance и freshness.
### 8.5. Topic
Тематический маршрут знаний.
Например:
- `container-deployment`;
- `network-attachment`;
- `profile-management`;
- `backup-and-restore`.
Для `container.deploy` агент получает первые нужные темы, но не читает всю документацию про backup, clustering и обновление платформы.
### 8.6. KnowledgeDocument
Конкретный Markdown, YAML, PDF, HTML snapshot, runbook или внешний URL.
Один документ может использоваться несколькими topics. Поэтому documents хранятся единым реестром, а topics ссылаются на их IDs.
### 8.7. Provenance
Ответ на вопрос «откуда это известно»:
- исходный URL;
- vendor;
- версия;
- дата получения;
- hash локальной копии;
- способ проверки.
Provenance отделяет официальную vendor information от локального правила и от наблюдаемого runtime fact.
### 8.8. Freshness
Ответ на вопрос «можно ли ещё доверять этим данным».
Если срок проверки истёк, информация не удаляется. Она помечается stale, а агент перед важным действием должен обновить или проверить её.
### 8.9. ContextBundle
Минимальный пакет контекста, который `repoctl` сформировал для одного intent.
Он содержит только:
- краткое описание contract;
- нужные content roots;
- подходящие operations;
- выбранные topics и documents;
- warnings о stale или missing information.
```mermaid
flowchart LR
Q["Запрос пользователя"] --> I["Intent"]
I --> C["Contract operations"]
I --> T["KDB topics"]
C --> B["ContextBundle"]
T --> B
B --> A["Небольшой контекст агента"]
ALL["Весь репозиторий и вся KDB"] -. "не загружаются" .-> A
```
Это основной механизм экономии времени и токенов.
## 9. Сущности: взаимодействие репозиториев
### 9.1. Consumer
Репозиторий, которому что-то нужно.
В примере с антивирусом consumer — `Services/Antivirus`. Он знает требования продукта и критерии успешности.
### 9.2. Provider
Репозиторий, предоставляющий техническую возможность.
В примере:
- LXD предоставляет контейнер;
- Network предоставляет сетевое подключение;
- Monitoring предоставляет наблюдаемость.
### 9.3. Capability
Тип возможности провайдера.
Пример: `compute.lxd-container` означает «этот repository умеет предоставлять управляемые LXD containers». Это ещё не конкретный контейнер.
### 9.4. Requirement
Потребность consumer repository.
Antivirus может потребовать:
- 4 CPU;
- 8 GiB memory;
- подключение к services network;
- определённые acceptance operations.
Requirement принадлежит Antivirus, потому что LXD не должен угадывать потребности продукта.
### 9.5. Binding
Связь requirement с конкретным реализованным ресурсом.
Например:
```text
Antivirus requirement
→ lxd://drweb/dwcp
```
Binding принадлежит provider repository. Он появляется после выбора или создания target и становится active только после verification и acceptance.
### 9.6. Acceptance
Проверки, доказывающие, что задача consumer решена.
LXD может подтвердить, что контейнер запущен и имеет правильный профиль. Только Antivirus может подтвердить, что базы обновляются и control plane действительно работает.
```mermaid
flowchart LR
S["Service consumer"] --> R["Requirement"]
P["Infrastructure provider"] --> C["Capability"]
R --> M{"Совместимы?"}
C --> M
M -->|"да"| B["Binding to concrete target"]
B --> V["Provider verification"]
V --> A["Consumer acceptance"]
A -->|"успех"| ACTIVE["Active binding"]
```
## 10. Сущности: безопасное выполнение
### 10.1. Operation
Публично объявленное действие репозитория.
Примеры:
- `container.inspect`;
- `container.plan`;
- `container.apply`;
- `container.verify`;
- `knowledge.validate`.
Operation сообщает назначение, intent, фазу, effect, risk, schemas, preconditions и канонический handler.
### 10.2. Handler
Единственная исполняемая реализация operation.
Это может быть Python, PowerShell, shell, Terraform или Ansible. Важно не средство, а то, что handler лежит в одном каноническом месте и ограничен своим доменом.
Skill не копирует handler. Claude не конструирует произвольные команды, если существует operation.
### 10.3. Effect и risk
Effect описывает, что операция способна изменить:
- `read-only`;
- `local-write`;
- `external-write`;
- `disruptive`;
- `destructive`.
Risk показывает серьёзность возможных последствий: `low`, `medium`, `high`, `critical`.
Effect и risk нужны для автоматического выбора approval policy.
### 10.4. Preconditions
Проверяемые условия до запуска:
- contract валиден;
- знания не stale;
- target входит в разрешённую область;
- revision не изменилась;
- binding существует;
- approval относится к текущему plan.
При нарушении precondition операция останавливается, а не «пробует всё равно».
## 11. Desired, observed, status и drift
```mermaid
flowchart LR
G["Git desired state"] --> D["Diff"]
R["Runtime observed state"] --> D
R --> S["Immutable snapshot"]
S --> D
D --> DRIFT{"Drift exists?"}
DRIFT -->|"нет"| READY["Ready condition"]
DRIFT -->|"да"| PLAN["Plan or warning"]
PLAN -. "только после approval" .-> APPLY["Apply"]
APPLY --> VERIFY["Verify"]
VERIFY --> R
```
### 11.1. Desired state
То, что должно быть. Хранится в authored files в Git.
### 11.2. Observed state
То, что фактически обнаружено в LXD, Docker, AD, Network или другой системе. Всегда имеет время наблюдения и provenance.
### 11.3. Snapshot
Неизменяемая историческая копия observed state. Snapshot полезен для diff, plan, расследования и rollback, но не является desired state.
### 11.4. Status и condition
Status — краткое производное состояние сущности.
Condition — отдельный стандартизованный факт, например:
- `ContractValid=True`;
- `KnowledgeFresh=False`;
- `DriftDetected=True`;
- `Ready=Unknown`.
Condition содержит reason, message, observed revision и время.
### 11.5. Drift
Разница между desired и observed state. Наличие drift не даёт автоматического разрешения на исправление: иногда нужен только warning, иногда — новый Plan.
## 12. Plan, apply и доказательство результата
### 12.1. Plan
Неизменяемое описание точных будущих изменений.
Plan фиксирует:
- intent;
- Git revisions;
- snapshots;
- targets;
- порядок operations;
- effects и risks;
- checkpoints;
- verification;
- rollback;
- собственный hash.
### 12.2. Revision и plan hash
Revision указывает точную версию входных данных. Plan hash идентифицирует точный план.
Если после планирования contract, desired state или важный snapshot изменился, старое approval больше не должно разрешать apply.
### 12.3. Approval
Разрешение конкретного пользователя на конкретный plan hash и targets. Approval не является общим разрешением «делать любые изменения в LXD».
### 12.4. Apply
Выполняет сохранённый Plan. Он не должен заново придумывать операции или расширять scope.
### 12.5. Checkpoint
Промежуточная остановка и проверка. Следующий шаг выполняется только после успешного результата предыдущего provider change и его проверки.
### 12.6. Verify
Проверяет технический результат provider. Успешный exit code apply ещё не доказывает правильность состояния.
### 12.7. Run и RunEvidence
Run — одно конкретное выполнение workflow.
RunEvidence — структурированное доказательство:
- какой plan выполнялся;
- кем и когда;
- какие шаги прошли;
- что проверил provider;
- прошла ли consumer acceptance;
- какой target был создан;
- что было redacted.
### 12.8. Reconcile и rollback
Reconcile повторно сравнивает desired и observed state и решает, нужен ли warning или новый Plan.
Rollback восстанавливает предыдущее состояние либо выполняет компенсирующее действие. Не все изменения полностью обратимы, поэтому невозможность rollback должна быть указана честно.
```mermaid
stateDiagram-v2
[*] --> Describe
Describe --> Inspect
Inspect --> Validate
Validate --> Diff
Diff --> Plan: change required
Diff --> Verify: no change required
Plan --> AwaitApproval: write effect
Plan --> Apply: local safe operation
AwaitApproval --> Apply: approved plan hash
AwaitApproval --> [*]: denied or stale
Apply --> Verify
Verify --> Accepted: provider and consumer checks pass
Verify --> Rollback: failed and rollback available
Verify --> Reconcile: drift remains
Rollback --> Verify
Reconcile --> Inspect
Accepted --> [*]
```
## 13. Workflow
Workflow связывает несколько operations ради пользовательского результата. Он координирует репозитории, но не копирует реализации handlers.
Пример: развернуть контейнер для антивируса.
```mermaid
sequenceDiagram
actor User as Пользователь
participant Agent as Claude
participant Repoctl as repoctl
participant AV as Services/Antivirus
participant LXD as Infra/LXD
participant Runtime as LXD runtime
User->>Agent: Разверни контейнер для антивируса
Agent->>Repoctl: context(intent=container.deploy)
Repoctl->>AV: Read contract and selected KDB topics
Repoctl->>LXD: Read contract and selected KDB topics
AV-->>Repoctl: Requirement and acceptance operation
LXD-->>Repoctl: Capability and provider operations
Repoctl-->>Agent: ContextBundle and relation graph
Agent->>Repoctl: inspect and build Plan
Repoctl->>Runtime: Read observed state
Runtime-->>Repoctl: Snapshot
Repoctl-->>User: Exact Plan, risk and plan hash
User->>Repoctl: Approve plan hash
Repoctl->>LXD: Apply provider step
LXD->>Runtime: Create or update container
Runtime-->>LXD: Result
LXD-->>Repoctl: Provider verification
Repoctl->>AV: Run consumer acceptance
AV-->>Repoctl: Acceptance passed
Repoctl-->>Agent: Active binding and RunEvidence
Agent-->>User: Container deployed and verified
```
Cross-repository workflow не является атомарной транзакцией. Безопасность достигается immutable Plan, последовательными checkpoints, verification, acceptance и evidence.
## 14. Интерфейсы для агентов и людей
### 14.1. `repoctl`
Общий диспетчер. Он не заменяет LXD, Docker, Git, Terraform или Ansible.
MVP-команды:
```text
repoctl init
repoctl adopt
repoctl validate
repoctl discover
repoctl describe
repoctl context
```
### 14.2. `AGENTS.md`
Короткая переносимая инструкция: что это за repository, где contract, как получить контекст и какие safety rules обязательны.
### 14.3. `CLAUDE.md`
Главный runtime entrypoint, потому что основной агент — Claude. Он импортирует `AGENTS.md` и содержит только Claude-specific дополнения.
### 14.4. Skill
Удобная команда или инструкция для типового intent, например `repository-adoption` или `repo-handoff`. Skill выбирает нужную операцию, но не реализует её заново. Для adoption источником истины остаётся [runbook](adoption-runbook.md), поэтому процедура переносима между Claude и другими агентами.
### 14.5. Adapter
Тонкий слой для конкретного harness: Claude skill, Codex skill, IDE command, CI job или MCP tool.
### 14.6. MCP
Будущий сетевой transport. Он публикует те же contracts, context bundles и operations. Добавление MCP не меняет владельца данных и не даёт write permission само по себе.
```mermaid
flowchart TB
CORE["Contract + KDB + repo-local handlers"] --> CLI["repoctl CLI"]
CORE --> CLAUDE["Claude adapter"]
CORE --> OTHER["Other agent adapter"]
CORE --> CI["CI validation"]
CORE -. "позже" .-> MCP["MCP server"]
CLI --> SAME["Одинаковая семантика"]
CLAUDE --> SAME
OTHER --> SAME
CI --> SAME
MCP --> SAME
```
## 15. Простая первая версия
Первая версия намеренно read-only вне явно подтверждённых `init` и `adopt --mode apply`.
```mermaid
flowchart LR
A["Phase A: schema/parser"] --> B["Phase B: validate/discover/describe/context"]
B --> C["Phase C: bootstrap, adoption and template lineage"]
C --> D["Phase D: LXD + Antivirus pilots"]
D --> E["Phase E: operation ABI and Plan"]
E --> F["Scoped apply and optional MCP"]
```
### 15.1. Что реализуем сейчас
- parser для `RepositoryContract` и `KnowledgeBase`;
- validation;
- безопасную работу с repo-relative paths;
- discovery и производный catalog;
- `describe` без чтения всей KDB;
- `context` с exact intent routing и budget;
- bootstrap четырёх repository types;
- adoption существующих репозиториев через assess → plan → apply → verify;
- compatibility index для legacy KDB без массовой конвертации;
- template ID/version/revision;
- генерацию `AGENTS.md` и `CLAUDE.md`;
- YAML и JSON output;
- тестовые fixtures.
### 15.2. Что оставляем на следующий этап
- единый ABI для существующих handlers;
- фактический вызов operations;
- immutable Plan hashing;
- approvals;
- apply;
- RunEvidence storage;
- continuous reconciliation;
- MCP server.
При этом IDs, envelope и связи уже совместимы с этими расширениями.
## 16. Предлагаемая внутренняя структура `repoctl`
```mermaid
flowchart TB
CLI["cli"] --> MODEL["model"]
CLI --> COMMANDS["commands"]
COMMANDS --> VALIDATE["validation"]
COMMANDS --> DISCOVERY["discovery"]
COMMANDS --> CATALOG["catalog"]
COMMANDS --> CONTEXT["context selection"]
COMMANDS --> BOOTSTRAP["templates/bootstrap"]
COMMANDS --> ADOPTION["adoption"]
VALIDATE --> IO["YAML/JSON I/O"]
DISCOVERY --> IO
CATALOG --> MODEL
CONTEXT --> MODEL
BOOTSTRAP --> MODEL
ADOPTION --> MODEL
MODEL --> SCHEMA["versioned schemas"]
```
Модули должны оставаться независимыми:
- `model` не знает о CLI;
- `discovery` ничего не исполняет;
- `catalog` только агрегирует contracts;
- `context` выполняет детерминированный выбор;
- `bootstrap` сначала строит preview/diff;
- `adoption` сохраняет существующие authoritative paths и сначала строит assessment/plan;
- будущий `runner` добавляется отдельно и не расширяет права read-only команд.
## 17. Bootstrap нового и adoption существующего репозитория
```mermaid
sequenceDiagram
actor User as Пользователь
participant Init as repoctl init
participant Template as Template registry
participant Repo as New repository
participant Validate as Validator
User->>Init: type, name, owner, lifecycle
Init->>Template: Load trusted template version
Template-->>Init: Skeleton and defaults
Init-->>User: Preview files and optional SSH recommendation
User->>Init: Confirm local write
Init->>Repo: Write contract, KDB and entrypoints
Init->>Validate: Validate generated repository
Validate-->>User: Findings and final diff
```
Bootstrap предлагает, но не навязывает:
- уникальный SSH deploy key для repository-scoped automation;
- read-only доступ по умолчанию;
- отдельное безопасное место private key вне Git;
- CODEOWNERS/branch policy;
- type-specific content roots.
Он обязательно записывает происхождение шаблона, чтобы стандартную часть можно было обновить позднее.
Для существующего репозитория используется другая операция — `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
flowchart LR
EXISTING["Существующий repository"] --> ASSESS["Assess: только чтение"]
ASSESS --> PLAN["Plan: contract, roots, KDB adapter"]
PLAN --> REVIEW{"Владелец согласен?"}
REVIEW -->|нет| REFINE["Уточнить классификацию"]
REFINE --> PLAN
REVIEW -->|overlay| APPLY["Apply: только metadata layer"]
REVIEW -->|normalize| NORMALIZE["Approved recipe and rename map"]
NORMALIZE --> APPLY
APPLY --> VERIFY["Validate and verify"]
VERIFY --> PILOT["Добавить в catalog как pilot"]
```
Подробные правила, включая legacy KDB и существующие `CLAUDE.md`/`AGENTS.md`, находятся в [adoption-runbook.md](adoption-runbook.md).
## 18. Проверки MVP
Минимальный тестовый набор должен включать:
| Область | Позитивный тест | Негативный тест |
|---|---|---|
| Contract | четыре repository types | неизвестный type |
| Paths | repo-relative path | `../outside` и absolute path |
| IDs | уникальные stable IDs | duplicate repository/content/topic IDs |
| KDB routing | exact intent selects expected topics | нерелевантные topics не загружаются |
| Freshness | current verified source | expired source создаёт warning |
| Catalog | воспроизводимая пересборка | duplicate repository name |
| Relations | requirement находит capability | unresolved requirement создаёт warning |
| Security | harmless metadata | secret-shaped fields и shell string |
| Context budget | deterministic truncation | тихое усечение без warning запрещено |
| Agent entrypoint | Claude imports portable instructions | длинная копия KDB в `CLAUDE.md` |
| Adoption | legacy layout объявлен без перемещения | перезапись существующего KDB или domain content |
## 19. Как измерять пользу
Цель — не просто создать новые YAML-файлы. Пользу нужно измерять на реальных задачах.
Рекомендуемые метрики:
- время до первой правильной команды;
- количество файлов, прочитанных до начала работы;
- tokens/bytes загруженного repository context;
- количество повторных объяснений структуры пользователем;
- доля stale knowledge, обнаруженного до действия;
- доля operations с успешным verify;
- количество несовместимых или orphan bindings;
- количество разных копий одного handler;
- время onboarding нового repository;
- время обновления repository template.
Для проверки достаточно нескольких одинаковых сценариев до и после внедрения:
1. найти LXD profiles;
2. подготовить новый container для Antivirus;
3. найти все Docker stacks;
4. проверить monitoring configuration;
5. начать работу в незнакомом software repository;
6. найти deliverables и sources в project repository.
## 20. Как модель связана с внешними практиками
Эта схема не копирует один конкретный продукт. Она соединяет несколько зрелых подходов, оставляя их независимыми от выбранного agent harness.
| Наша часть | Близкая внешняя практика | Что заимствовано |
|---|---|---|
| Repo-local contract и производный catalog | [Backstage Software Catalog](https://backstage.io/docs/features/software-catalog/) | descriptor хранится рядом с repository content, catalog является проекцией |
| Bootstrap и обновление стандартной части | [Backstage Software Templates](https://backstage.io/docs/features/software-templates/), [Copier updates](https://copier.readthedocs.io/en/stable/updating/) | typed inputs, preview, template version, migrations |
| Desired/observed state и reconciliation | [OpenGitOps](https://opengitops.dev/), [Kubernetes API conventions](https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api-conventions.md) | декларативность, разделение spec/status, conditions и observed revision |
| Requirements и capabilities | [Crossplane composite resources](https://docs.crossplane.io/latest/composition/composite-resources/), [Score](https://docs.score.dev/docs/) | отделение потребности consumer от реализации provider |
| Operations и workflows | [OpenAPI](https://spec.openapis.org/oas/latest.html), [Arazzo](https://spec.openapis.org/arazzo/latest.html) | стабильные operation IDs, schemas, dependencies, outputs и success criteria |
| Claude и переносимые agent instructions | [Claude memory](https://code.claude.com/docs/en/memory), [AGENTS.md](https://agents.md/) | короткий постоянный entrypoint и on-demand подробности |
| Опциональный transport | [MCP server primitives](https://modelcontextprotocol.io/specification/2025-06-18/server/index) | resources, tools и prompts как адаптеры над общей моделью |
| KDB и provenance | [Data Package](https://specs.frictionlessdata.io/guides/data-package/), [W3C PROV](https://www.w3.org/TR/prov-o/), [Diátaxis](https://diataxis.fr/) | human/machine index, происхождение знания и типы документации |
| Repository security | [OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md), [SLSA provenance](https://slsa.dev/spec/v1.2/provenance), [SPDX](https://spdx.github.io/spdx-spec/v3.0.1/scope/) | ownership, protected changes, integrity и supply-chain provenance |
| Domain-native content roots | [Flux repository layouts](https://fluxcd.io/flux/guides/repository-structure/), [Terraform module structure](https://developer.hashicorp.com/terraform/language/modules/develop/structure), [Docker Compose project directory](https://docs.docker.com/reference/cli/docker/compose/) | стандартное место результата задаётся доменом, а contract только объявляет его |
Уникальная часть нашей модели — сочетание intent-based KDB routing, typed content roots, consumer-owned acceptance, provider-owned bindings и immutable cross-repository Plan. Внешние практики подтверждают отдельные элементы, но не дают эту комбинацию целиком.
## 21. Итоговая модель одной фразой
```mermaid
flowchart LR
REQUEST["Что хочет пользователь"] --> INTENT["Intent"]
INTENT --> CONTRACT["Кто отвечает и что умеет"]
INTENT --> KDB["Что нужно знать"]
CONTRACT --> ROOTS["Где лежит результат"]
CONTRACT --> RELATIONS["Кто от кого зависит"]
CONTRACT --> OPERATIONS["Что разрешено сделать"]
KDB --> CONTEXT["Минимальный нужный контекст"]
ROOTS --> CONTEXT
RELATIONS --> CONTEXT
OPERATIONS --> CONTEXT
CONTEXT --> PLAN["Что именно изменится"]
PLAN --> RESULT["Проверенный результат и evidence"]
```
В коротком виде:
- **Contract** — кто мы и как с нами работать;
- **Intent** — чего хочет пользователь;
- **KDB** — что нужно знать для этой цели;
- **ContentRoot** — где находится реальный результат;
- **Requirement** — что нужно consumer;
- **Capability** — что умеет provider;
- **Binding** — какой конкретный target удовлетворил requirement;
- **Operation** — что разрешено сделать;
- **Handler** — как это технически выполняется;
- **Plan** — какие точные изменения подтверждаются;
- **RunEvidence** — чем доказан итог;
- **repoctl / skill / MCP** — разные интерфейсы над одной моделью.