feat: add ownership-aware template updates

README.md

@@ -52,7 +52,7 @@ problem space            solution space             execution space
 
 ## Внедрение в проект
 
-В downstream-проект обычно копируется только каталог `memory-bank/`. Исходники CLI, Go-модуль, CI и release-конфигурация этого репозитория не являются частью шаблона приложения.
+В downstream-проект устанавливается каталог `memory-bank/` и создаётся ownership lock рядом с ним. Исходники CLI, Go-модуль, CI и release-конфигурация этого репозитория не являются частью шаблона приложения.
 
 Инструкция по внедрению охватывает:
 
@@ -76,6 +76,7 @@ problem space            solution space             execution space
 | [Внедрение Memory Bank](docs/adoption.md) | Для команд, подключающих шаблон к brownfield- или greenfield-проекту |
 | [Использование Memory Bank](docs/usage.md) | Для повседневной работы с задачами и AI-агентами после внедрения |
 | [Установка и использование `memory-bank`](docs/memory-bank.md) | Для пользователей CLI и downstream CI |
+| [Ownership и безопасные обновления](docs/ownership.md) | Для понимания lock schema, границ владения и conflict policy |
 | [Разработка репозитория](docs/development.md) | Для разработчиков шаблона и CLI |
 
 `memory-bank lint` проверяет broken links, orphan-документы, достижимость через индексную навигацию и contract ожидаемых `README.md`-индексов. Прежний `memory-bank-lint` временно остаётся совместимым entrypoint для существующей автоматизации.

docs/adoption.md

@@ -1,24 +1,26 @@
 # Внедрение Memory Bank в проект
 
-Этот документ описывает, как подключить Memory Bank к существующему или новому проекту. В downstream-проект обычно копируется только каталог `memory-bank/`; dev-инфраструктура этого репозитория (`cmd/`, `.github/`, `.goreleaser.yml`, `go.mod`, `docs/`) не является частью шаблона приложения.
+Этот документ описывает, как подключить Memory Bank к существующему или новому проекту. В downstream-проект устанавливается каталог `memory-bank/`, а внутри него создаётся служебный `memory-bank/.lock`; dev-инфраструктура этого репозитория (`cmd/`, `.github/`, `.goreleaser.yml`, `go.mod`, `docs/`) не является частью шаблона приложения. Lock создаёт `memory-bank init`, а не upstream template. Его нужно коммитить: он хранит версию источника и ownership-границу для безопасных обновлений.
 
 ## Что копировать
 
-Минимальный переносимый комплект:
+Минимальный установленный комплект:
 
 ```text
 memory-bank/
+  .lock
 ```
 
-Для первичной установки на macOS или Linux выполните из корня downstream-проекта:
+Установите CLI и подготовьте локальный checkout шаблона на конкретном commit, затем выполните из корня downstream-проекта:
 
 ```bash
-test ! -e ./memory-bank &&
-  curl -fsSL https://github.com/dapi/memory-bank/archive/refs/heads/main.tar.gz |
-  tar -xz --strip-components=1 memory-bank-main/memory-bank
+memory-bank init \
+  --source /path/to/memory-bank-checkout \
+  --template-version VERSION \
+  --source-ref FULL_COMMIT_SHA
 ```
 
-Команда останавливается, если `memory-bank/` уже существует, и не перезаписывает адаптированные документы. На других платформах скачайте source archive этого репозитория и скопируйте из него только каталог `memory-bank/`.
+Команда не перезаписывает адаптированные и пользовательские документы. Для уже скопированного template она создаст lock поверх совпадающих файлов. Если managed-файл отличается от выбранного source, сначала разберите conflict. Подробный ownership-контракт и процедура обновления: [`ownership.md`](ownership.md).
 
 Опционально добавьте в downstream-проект собственный `AGENTS.md`, `CLAUDE.md` или аналогичный файл с правилом начинать работу с:
 
@@ -35,7 +37,7 @@ memory-bank/dna/README.md
 
 Цель brownfield-внедрения — сделать текущий контекст проекта видимым и проверяемым для людей и агентов. Не начинайте с идеального описания будущей архитектуры. Сначала зафиксируйте то, что уже влияет на разработку: реальные пользователи, термины, ограничения, интеграции, принятые решения, неочевидные правила и known gaps.
 
-1. Скопируйте каталог `memory-bank/` в корень проекта.
+1. Установите каталог `memory-bank/` и lock через `memory-bank init`.
 2. Добавьте в `AGENTS.md`, `CLAUDE.md` или аналогичный файл инструкцию начинать работу с `memory-bank/README.md`.
 3. Проведите inventory существующего кода, документации, терминов, архитектурных решений и процессов.
 4. Адаптируйте `product/`, `domain/`, `engineering/` и `ops/`. В `engineering/ui-design-guide/` заполните draft-заготовки для реальных UI surfaces и удалите неприменимые файлы вместе со ссылками из index. Не выдумывайте отсутствующие знания: отмечайте пробелы и вопросы явно.
@@ -221,7 +223,7 @@ jobs:
 
 Memory Bank считается внедрённым, когда:
 
-- `memory-bank/` находится в корне downstream-проекта;
+- `memory-bank/` с закоммиченным служебным `.lock` находится в корне downstream-проекта;
 - постоянный контекст `product/`, `domain/`, `engineering/` и `ops/` отражает фактические правила проекта или явно помечает пробелы;
 - агентские инструкции указывают читать `memory-bank/README.md` и governance-ядро;
 - первая реальная задача прошла через выбранный flow или `Small Change` routing record;

docs/memory-bank.md

@@ -1,6 +1,14 @@
 # CLI memory-bank
 
-`memory-bank lint` проверяет навигационную целостность `memory-bank/`:
+`memory-bank` безопасно устанавливает и обновляет template, а также проверяет навигационную целостность `memory-bank/`.
+
+Ownership-контракт, классы файлов и atomic update policy описаны в [отдельном документе](ownership.md). Основные команды:
+
+- `memory-bank init` создаёт служебный `memory-bank/.lock` и устанавливает только отсутствующие файлы;
+- `memory-bank update` строит ownership-aware mutation plan и применяет его только целиком;
+- `memory-bank lint` проверяет документацию.
+
+`memory-bank lint` обнаруживает:
 
 - broken relative markdown links внутри audit scope;
 - orphan-документы, на которые никто не ссылается внутри scope;
@@ -91,7 +99,7 @@ go run github.com/dapi/memory-bank/cmd/memory-bank@latest lint
 - exit code `0` означает успешную команду без lint errors, `1` — lint errors или operational failure, `2` — неверный вызов CLI;
 - repo root находится по ближайшему родительскому `.git`, а `--repo-root` переопределяет discovery.
 
-CLI спроектирован для расширения командами `init`, `update`, `doctor` и `adapt brownfield`. Они не реализованы в текущем релизе; в частности, автоматическая brownfield-адаптация не входит в `memory-bank lint`.
+`init` и `update` принимают `--source`, `--template-version`, `--source-ref`, `--repo-root`, `--dry-run` и `--json`. Команда `doctor` и автоматическая brownfield-адаптация остаются отдельными будущими возможностями и не входят в `memory-bank lint`.
 
 ## Переход с memory-bank-lint
 

docs/ownership.md

@@ -0,0 +1,51 @@
+# Ownership и безопасные обновления
+
+`memory-bank/.lock` — служебный контракт между downstream-проектом и версией шаблона. Файл создаётся командой `memory-bank init` внутри установленного `memory-bank/` и коммитится вместе с ним; из upstream template он не копируется. Формальная схема: [`schema/memory-bank-lock-v1.schema.json`](schema/memory-bank-lock-v1.schema.json).
+
+## Классы владения
+
+| Класс | Текущая граница шаблона | Поведение update |
+| --- | --- | --- |
+| `managed` | `memory-bank/dna/`, `flows/`, `prompts/`, а также top-level template-индексы `prd/README.md`, `epics/README.md`, `use-cases/README.md`, `features/README.md`, `adr/README.md` | Проверяет текущий payload по digest. Чистый файл обновляется или удаляется; локальный drift становится conflict. |
+| `adapted` | `memory-bank/README.md`, `product/`, `domain/`, `engineering/`, `ops/` | Хранит digest исходной template-base, но не требует совпадения текущего файла. Чистый файл может получить новую base; одновременные upstream и downstream изменения становятся conflict. |
+| `user-owned` | Instantiated-документы в `prd/`, `epics/`, `use-cases/`, `features/`, `adr/` и неизвестные downstream paths | Никогда автоматически не перезаписывается и не удаляется. Неизвестный существующий файл получает этот класс по fail-safe правилу. |
+| `generated` | `memory-bank/.generated/` зарезервирован для будущих детерминированных генераторов; в текущем template таких файлов нет | Может быть пересоздан или удалён только детерминированным producer. |
+
+`base_digest` и `base_mode` (`100644` или `100755`) описывают файл в зафиксированной template-base. `payload_digest` и `payload_mode` присутствуют только там, где текущий файл является проверяемым managed/generated contract. Поэтому обычная специализация adapted-документа не считается drift, а изменение executable bit managed-файла проверяется так же, как изменение его содержимого.
+
+## Init и update
+
+Команды работают с локальным checkout источника, закреплённым на immutable commit. CLI не делает network fetch и не доверяет moving branch автоматически:
+
+```bash
+memory-bank init \
+  --source /path/to/memory-bank-checkout \
+  --template-version v1.2.3 \
+  --source-ref FULL_COMMIT_SHA
+```
+
+`--source` должен указывать на корень чистого Git checkout, `--source-ref` — в точности совпадать с его `HEAD`. Незакоммиченные, untracked или ignored payloads внутри `memory-bank/` отклоняются, как и source, совпадающий с downstream repo либо вложенный в него через обычный путь или symlink. Payload и executable modes читаются непосредственно из объектов закреплённого commit, поэтому обычные Git text conversions (`core.autocrlf`, `.gitattributes`) не создают ложный drift и не меняют устанавливаемые байты.
+
+`init` подходит и для пустого проекта, и для ранее скопированного `memory-bank/`: существующие adapted/user-owned файлы принимаются без перезаписи. Несовпадающий существующий managed-файл останавливает инициализацию как conflict.
+
+Перед обновлением сначала проверьте полный plan:
+
+```bash
+memory-bank update \
+  --source /path/to/new-memory-bank-checkout \
+  --template-version v1.3.0 \
+  --source-ref FULL_COMMIT_SHA \
+  --dry-run
+```
+
+Добавьте `--json` для machine-readable report format `1`. Каждому известному пути назначается одно решение: `create`, `update`, `preserve`, `conflict` или `delete`. Conflict даёт exit code `1`, сохраняет исходные файлы и lock и требует ручного разрешения. Чтобы принять incoming template, замените конфликтующий файл его incoming payload и повторите update: совпадение digest будет принято как новая base и записано в lock. Для сохранения другого варианта скорректируйте ownership осознанной миграцией lock; команда никогда не выбирает победителя молча.
+
+Без `--dry-run` сначала строится и проверяется весь plan. При наличии хотя бы одного conflict ничего не применяется. Все новые payload заранее записываются в repo-local temporary staging, существующие файлы перемещаются туда перед заменой, а lock заменяется последним. Planned digests повторно проверяются перед мутацией и перед commit lock. Clean-managed изменения topology `file → directory` и `directory → file` применяются в той же транзакции: прежние payload сначала сохраняются в staging, затем создаётся новая форма пути. Ошибка во время применения откатывает уже сделанные изменения и структуру каталогов без повторной записи содержимого; если rollback или очистка не могут завершиться, команда возвращает явную ошибку и сохраняет staging с recovery-копиями. Успешный no-op не переписывает lock, поэтому повторный update идемпотентен.
+
+Корень downstream-репозитория закрепляется по filesystem identity на весь run. Destination-мутации выполняются относительно уже открытых directory handles: через `openat`-семейство на Unix и через handle-relative NT APIs на Windows. Поэтому замена ранее проверенного parent на symlink или junction не может перенаправить операцию наружу. Symlink или reparse point в любом компоненте ниже корня, включая сам managed-файл или lock, считается unsafe path: команда завершается ошибкой и не читает и не изменяет target ссылки.
+
+## Версионирование
+
+`schema_version` версионирует lock contract независимо от версии template. CLI читает schema `1`; неизвестная версия завершается ошибкой без мутаций. Unversioned prototype со значением `0` имеет семантику v1 и атомарно переписывается в schema `1` при следующем успешном update.
+
+`template.version` — понятная человеку версия, `template.source_ref` — immutable идентификатор фактического source checkout. `last_update` меняется только вместе с успешной сменой template state или миграцией schema.