--- 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** — разные интерфейсы над одной моделью.