dapi · dapi · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/README.md b/README.md
@@ -78,6 +78,7 @@ problem space            solution space             execution space
 | [Использование Memory Bank](docs/usage.md) | Для повседневной работы с задачами и AI-агентами после внедрения |
 | [Установка и использование `memory-bank`](docs/memory-bank.md) | Для пользователей CLI и downstream CI |
 | [Ownership и безопасные обновления](docs/ownership.md) | Для понимания lock schema, границ владения и conflict policy |
+| [Managed-блок инструкций агента](docs/agent-instructions.md) | Для marker contract, doctor и выбора единственного agent instruction target |
 | [Разработка репозитория](docs/development.md) | Для разработчиков шаблона и CLI |
 
 `memory-bank lint` проверяет broken links, orphan-документы, достижимость через индексную навигацию и contract ожидаемых `README.md`-индексов. Прежний `memory-bank-lint` временно остаётся совместимым entrypoint для существующей автоматизации.

diff --git a/docs/adoption.md b/docs/adoption.md
@@ -22,12 +22,7 @@ memory-bank init \
 
 Команда не перезаписывает адаптированные и пользовательские документы. Для уже скопированного template она создаст lock поверх совпадающих файлов. Если managed-файл отличается от выбранного source, сначала разберите conflict. Подробный ownership-контракт и процедура обновления: [`ownership.md`](ownership.md).
 
-Опционально добавьте в downstream-проект собственный `AGENTS.md`, `CLAUDE.md` или аналогичный файл с правилом начинать работу с:
-
-```text
-memory-bank/README.md
-memory-bank/dna/README.md
-```
+`init` также безопасно создаёт или обновляет [managed-блок agent instructions](agent-instructions.md) в корневом `AGENTS.md`. Существующий текст вне markers сохраняется. Если проект использует другой файл, передайте единственный явный target, например `--agent-file CLAUDE.md`; CLI не создаёт конкурирующие блоки автоматически.
 
 Не копируйте весь репозиторий `dapi/memory-bank` как основу продукта, если вам не нужна разработка самого шаблона и CLI. Иначе в downstream-проект попадут CI/release-файлы шаблона, Go-модуль и исходники `memory-bank`.
 
@@ -38,7 +33,7 @@ memory-bank/dna/README.md
 Цель brownfield-внедрения — сделать текущий контекст проекта видимым и проверяемым для людей и агентов. Не начинайте с идеального описания будущей архитектуры. Сначала зафиксируйте то, что уже влияет на разработку: реальные пользователи, термины, ограничения, интеграции, принятые решения, неочевидные правила и known gaps.
 
 1. Установите каталог `memory-bank/` и lock через `memory-bank init`.
-2. Добавьте в `AGENTS.md`, `CLAUDE.md` или аналогичный файл инструкцию начинать работу с `memory-bank/README.md`.
+2. Проверьте созданный `init` managed-блок в `AGENTS.md` или укажите alternative target через `--agent-file`.
 3. Проведите inventory существующего кода, документации, терминов, архитектурных решений и процессов.
 4. Адаптируйте `product/`, `domain/`, `engineering/` и `ops/`. В `engineering/ui-design-guide/` заполните draft-заготовки для реальных UI surfaces и удалите неприменимые файлы вместе со ссылками из index. Не выдумывайте отсутствующие знания: отмечайте пробелы и вопросы явно.
 5. Перенесите устойчивые сценарии в `use-cases/`, а значимые принятые решения — в ADR.
@@ -103,7 +98,7 @@ codex --search \
 
 ## Подключить агента
 
-Добавьте в `AGENTS.md`, `CLAUDE.md` или аналогичный файл правило начинать работу с `memory-bank/README.md` и `memory-bank/dna/README.md`. Если файл уже содержит project-specific инструкции, дополните их маршрутизацией в Memory Bank, не заменяя существующие правила проекта.
+Используйте managed-блок, который устанавливает `memory-bank init`: он направляет агента к `memory-bank/README.md`, `memory-bank/dna/README.md` и `memory-bank/flows/routing.md`, не копируя governance. Не редактируйте содержимое между markers вручную; project-specific инструкции размещайте снаружи. Полный marker, update, doctor и alternative-target contract описан в [managed-блоках agent instructions](agent-instructions.md).
 
 Для первой адаптации можно использовать запрос:
 

diff --git a/docs/agent-instructions.md b/docs/agent-instructions.md
@@ -0,0 +1,44 @@
+# Managed-блок инструкций агента
+
+`memory-bank init` и `memory-bank update` управляют только коротким routing-блоком в agent instruction file. По умолчанию target — корневой `AGENTS.md`:
+
+```markdown
+<!-- MEMORY BANK START -->
+<!-- MEMORY BANK MANAGED BLOCK VERSION: 1 -->
+Before substantial delivery work, read memory-bank/README.md, memory-bank/dna/README.md, and memory-bank/flows/routing.md.
+Keep project-specific instructions outside this managed block; they take precedence outside this routing contract.
+<!-- MEMORY BANK END -->
+```
+
+Markers — стабильная граница ownership только тогда, когда каждый marker занимает отдельную строку без отступов или другого текста. Строка `MEMORY BANK MANAGED BLOCK VERSION` версионирует payload независимо от markers. Governance остаётся в `memory-bank/`; блок только направляет агента к canonical documents и не становится вторым source of truth.
+
+## Правила обновления
+
+- Если markers отсутствуют, CLI создаёт файл или добавляет блок в конец существующего файла.
+- Между существующим текстом и новым блоком добавляется одна пустая строка. Если последняя строка не была завершена, CLI сначала добавляет newline; остальные существующие bytes не меняются.
+- Если ровно одна корректная пара markers содержит старый payload, CLI заменяет только bytes от start marker до end marker и следующий за ним `LF`, если он есть. Весь текст до и после сохраняется byte-for-byte.
+- Актуальный блок — no-op: повторный `init/update` не создаёт diff блока.
+- Несовпадающее количество markers, несколько пар, end marker перед start marker, повреждённый marker или его inline-упоминание — conflict. CLI не изменяет ни agent file, ни template, ни lock.
+
+`init/update --dry-run` печатает planned block diff в text output и в поле `decisions[].diff` JSON report. Применение блока входит в общую атомарную транзакцию template update. Если меняется только блок, template lock и его `last_update` не переписываются.
+
+## Doctor
+
+```bash
+memory-bank doctor
+memory-bank doctor --json
+```
+
+`doctor` проверяет блок без мутаций. Missing и outdated block дают planned `create/update`, ambiguous markers — `conflict`, актуальный блок — `preserve`. Любой drift возвращает exit code `1`; актуальное состояние — `0`. JSON дополнительно содержит `drift_count` и `conflict_count`.
+
+## Альтернативный target
+
+Canonical default — только `AGENTS.md`. Для проекта, который использует другой instruction file, задайте один repo-relative target явно и одинаково во всех командах:
+
+```bash
+memory-bank init ... --agent-file CLAUDE.md
+memory-bank update ... --agent-file CLAUDE.md
+memory-bank doctor --agent-file CLAUDE.md
+```
+
+CLI не создаёт блоки одновременно в нескольких файлах и не принимает target внутри `memory-bank/`. Project-specific инструкции должны оставаться вне managed markers; CLI никогда их не переписывает, и они имеют приоритет за пределами минимального routing contract.
diff --git a/docs/memory-bank.md b/docs/memory-bank.md
@@ -6,6 +6,7 @@ Ownership-контракт, классы файлов и atomic update policy о
 
 - `memory-bank init` создаёт служебный `memory-bank/.lock` и устанавливает только отсутствующие файлы;
 - `memory-bank update` строит ownership-aware mutation plan и применяет его только целиком;
+- `memory-bank doctor` проверяет актуальность managed-блока agent instructions;
 - `memory-bank lint` проверяет документацию.
 
 `memory-bank lint` обнаруживает:
@@ -99,7 +100,7 @@ go run github.com/dapi/memory-bank/tools/cmd/memory-bank@latest lint
 - exit code `0` означает успешную команду без lint errors, `1` — lint errors или operational failure, `2` — неверный вызов CLI;
 - repo root находится по ближайшему родительскому `.git`, а `--repo-root` переопределяет discovery.
 
-`init` и `update` принимают `--source`, `--template-version`, `--source-ref`, `--repo-root`, `--dry-run` и `--json`. Команда `doctor` и автоматическая brownfield-адаптация остаются отдельными будущими возможностями и не входят в `memory-bank lint`.
+`init` и `update` принимают `--source`, `--template-version`, `--source-ref`, `--repo-root`, `--agent-file`, `--dry-run` и `--json`. Они также управляют коротким versioned routing-блоком в `AGENTS.md`; `--agent-file` выбирает один alternative target. `doctor` принимает `--repo-root`, `--agent-file` и `--json` и проверяет этот блок без мутаций. Подробности: [managed-блок инструкций агента](agent-instructions.md). Автоматическая brownfield-адаптация не входит в CLI.
 
 ## Переход с memory-bank-lint
 

diff --git a/docs/ownership.md b/docs/ownership.md
@@ -40,7 +40,7 @@ memory-bank update \
 
 Добавьте `--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 идемпотентен.
+Без `--dry-run` сначала строится и проверяется весь plan. При наличии хотя бы одного conflict ничего не применяется. Все новые payload, включая [managed-блок agent instructions](agent-instructions.md), заранее записываются в 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 ссылки.