docs: add brownfield adaptation protocol

README.md

@@ -75,6 +75,7 @@ problem space            solution space             execution space
 | Документ | Для кого и зачем |
 | --- | --- |
 | [Внедрение Memory Bank](docs/adoption.md) | Для команд, подключающих шаблон к brownfield- или greenfield-проекту |
+| [Brownfield adaptation protocol](docs/brownfield-adaptation-protocol.md) | Для evidence-backed адаптации существующего репозитория до и после установки Memory Bank |
 | [Greenfield adaptation protocol](docs/greenfield-integration-protocol.md) | Для копирования шаблона, извлечения project facts из README и docs, адаптации Memory Bank и создания initial PRD |
 | [Использование Memory Bank](docs/usage.md) | Для повседневной работы с задачами и AI-агентами после внедрения |
 | [Использование `memory-bank-cli`](docs/memory-bank.md) | Для пользователей CLI и downstream CI |

docs/adoption.md

@@ -14,58 +14,9 @@ memory-bank/
 
 ## Адаптировать существующий проект (brownfield)
 
-В существующем проекте Memory Bank сначала должен отразить реальное состояние продукта и разработки, а не желаемую картину.
+Для существующего проекта следуйте [brownfield adaptation protocol](brownfield-adaptation-protocol.md). Он начинает с evidence-backed discovery **до** установки и чтения `memory-bank/`, затем описывает intake PRD, adaptation canonical owners, governed conversion, validation и real-task trial.
 
-Цель brownfield-внедрения — сделать текущий контекст проекта видимым и проверяемым для людей и агентов. Не начинайте с идеального описания будущей архитектуры. Сначала зафиксируйте то, что уже влияет на разработку: реальные пользователи, термины, ограничения, интеграции, принятые решения, неочевидные правила и known gaps.
-
-1. Скопируйте каталог `memory-bank/`.
-2. Проведите inventory существующего кода, документации, терминов, архитектурных решений и процессов.
-3. Адаптируйте `product/`, `domain/`, `engineering/` и `ops/`. В `engineering/ui-design-guide/` заполните draft-заготовки для реальных UI surfaces и удалите неприменимые файлы вместе со ссылками из index. Не выдумывайте отсутствующие знания: отмечайте пробелы и вопросы явно.
-4. Перенесите устойчивые сценарии в `use-cases/`, а значимые принятые решения — в ADR.
-5. Проверьте подход на одной реальной задаче или фиче, прежде чем описывать весь проект.
-6. Запустите аудит ссылок и индексации.
-
-### Brownfield inventory
-
-Минимальный inventory перед первой адаптацией:
-
-- README, wiki, runbooks, ADR, старые design docs;
-- ключевые директории кода и границы модулей;
-- production/staging/local окружения;
-- внешние интеграции и владение credentials/config;
-- основные пользовательские сценарии и операционные сценарии;
-- термины, которые уже используются в коде, UI, API и команде;
-- текущий CI/CD и обязательные проверки перед merge;
-- известные технические долги, ограничения и опасные зоны.
-
-### Brownfield порядок заполнения
-
-1. `product/` — что продукт уже делает, для кого, какие outcomes и метрики реально важны.
-2. `domain/` — glossary, domain model, states/events/rules из существующей системы.
-3. `engineering/` — текущая архитектура, coding style, testing policy, frontend/backend conventions, git workflow.
-4. `ops/` — локальный запуск, окружения, config, release process, runbooks.
-5. `use-cases/` — только устойчивые сценарии, которые уже проверяются или должны проверяться.
-6. `adr/` — решения, которые уже приняты и продолжают влиять на разработку.
-
-Если факт неизвестен, пишите это явно: `Unknown`, `TBD`, `Needs owner confirmation`. Для агента это безопаснее, чем уверенная выдумка.
-
-### Brownfield типичные ошибки
-
-- описывать желаемую архитектуру как текущую;
-- переносить в Memory Bank все старые документы без нормализации и ownership;
-- создавать PRD/feature packages до описания базового product/domain/engineering context;
-- дублировать один и тот же факт в нескольких местах;
-- блокировать PR из-за устаревшей документации, которую команда ещё не готова исправлять.
-
-### Brownfield готовность
-
-Brownfield-внедрение достаточно для первого рабочего использования, когда:
-
-- агент может понять, как проект устроен, из `memory-bank/README.md` и owner-документов;
-- минимум `product/`, `domain/`, `engineering/` и `ops/` адаптированы под реальный проект;
-- known gaps явно отмечены;
-- одна реальная задача прошла через `Small Change`, feature package, bug fix или другой выбранный flow;
-- `memory-bank-cli lint` проходит локально.
+Не заменяйте protocol кратким inventory: порядок важен, потому что generic template не является источником project facts до завершения discovery.
 
 ## Начать новый проект (greenfield)
 
@@ -84,7 +35,7 @@ codex --search \
 
 Используйте managed-блок, который устанавливает `memory-bank-cli 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).
 
-Для первой адаптации можно использовать запрос:
+После установки Memory Bank для первой адаптации можно использовать запрос:
 
 ```text
 Прочитай ./memory-bank/README.md и governance-ядро в ./memory-bank/dna/.

docs/brownfield-adaptation-protocol.md

@@ -0,0 +1,191 @@
+# Протокол адаптации Memory Bank для brownfield-проекта
+
+## Цель и граница
+
+Этот protocol помогает добавить Memory Bank в уже существующий web service или
+CLI utility так, чтобы он отражал наблюдаемое состояние проекта, а не желаемую
+картину. Он не заменяет существующие repository instructions, документацию или
+код и не реализует продуктовые изменения.
+
+**До шага «Установить и активировать» не открывайте, не копируйте и не
+консультируйте `memory-bank/`, включая generic template, его README, governance
+и templates.** На этой стадии они не являются источником project knowledge:
+placeholders и generic rules нельзя принимать за facts текущего репозитория.
+
+Если repository sources противоречат друг другу или факта нет, не выбирайте
+молча: сохраните conflict или open question с источниками, confidence и owner,
+если он известен.
+
+## Источники pre-adaptation discovery
+
+Сначала прочитайте repository instructions (`AGENTS.md`, `CLAUDE.md` и
+эквиваленты), затем исследуйте только уже существующие project sources:
+
+- root и nested README, wiki, docs, runbooks, design docs и historical ADR;
+- source code, manifests, dependency files и critical code paths;
+- CI/CD, configuration, deployment/release definitions и observability assets;
+- existing task-tracker, operational и ownership references, доступные в scope.
+
+Не извлекайте и не копируйте secret values, PII, tokens или internal endpoints.
+Допустимо зафиксировать только owner и безопасный access procedure.
+
+## Lifecycle
+
+### 1. Pre-adaptation discovery
+
+Проведите inventory источников и зафиксируйте только наблюдаемые facts, их
+source references, freshness и confidence. На этой стадии Memory Bank не
+установлен и не используется.
+
+Минимальный inventory:
+
+- runtime modules, boundaries, dependencies и critical code paths;
+- API/UI contracts, clients, queues, scheduled jobs, webhooks и external
+  integrations;
+- configuration, feature flags, ownership/access procedure для secrets,
+  environments, CI/CD, release/rollback, migrations, observability, SLOs и
+  alerts;
+- existing docs/ADRs/runbooks, их owner и известные freshness concerns;
+- product terminology, key user/operational flows, technical debt, risky areas
+  и unresolved ownership.
+
+### 2. Создать intake PRD вне Memory Bank
+
+Создайте временный evidence-backed документ
+`./brownfield-intake-prd.md` в корне downstream repository. Этот путь —
+default; repository может использовать иной уже принятый путь только если он
+явно записан, находится вне `memory-bank/` и сохраняет все обязательные поля
+ниже.
+
+Intake PRD не governed document и не source of truth после conversion. Он
+содержит:
+
+- current product problem, users/jobs, goals, non-goals и scope;
+- success signals, risks, assumptions, open questions и conflicts;
+- source reference для каждого существенного факта, confidence и известного
+  owner/freshness;
+- inventory summary и список intentionally unadapted facts/documents.
+
+Не добавляйте invented architecture, selected solution, delivery plan, feature
+packages или epics. Unknown означает `Unknown`/`TBD`/`Needs owner confirmation`,
+а не правдоподобную догадку.
+
+### 3. Установить и активировать Memory Bank
+
+Только после завершения discovery скопируйте или инициализируйте `memory-bank/`
+по [инструкции CLI](memory-bank.md). Затем прочитайте
+`memory-bank/README.md`, governance-ядро и применимый flow. Сохраните existing
+repository instructions: managed agent block дополняет их, но не заменяет.
+
+### 4. Адаптировать canonical owners из тех же evidence
+
+Переносите durable facts из intake PRD в owner-документы без дублирования:
+
+| Owner layer | Что адаптировать |
+| --- | --- |
+| `product/` | Current product problem, users, jobs, outcomes, non-goals и известные success signals |
+| `domain/` | Glossary, actors, entities, states/events/rules и bounded contexts, подтверждённые sources |
+| `engineering/` | Architecture, module boundaries, technology/testing/coding/git conventions и technical constraints |
+| `ops/` | Local development, config ownership, environments, releases, rollback и runbooks |
+
+Отмечайте unknown, conflicts и owner-pending facts в соответствующем owner или
+явном gap/open-question record вместе с evidence. Для real UI surfaces заполните
+релевантные draft-заготовки в `engineering/ui-design-guide/`; неприменимые
+файлы и их index links удаляйте только после проверки, что они не нужны проекту.
+
+### 5. Govern intake PRD
+
+После адаптации только нужных upstream owners конвертируйте intake PRD в
+`memory-bank/prd/PRD-XXX-*.md` по PRD template. Governed PRD:
+
+- зависит через `derived_from` только от уже адаптированных relevant upstream
+  owners;
+- сохраняет source references, confidence, conflicts, assumptions и open
+  questions, а не превращает их в asserted facts;
+- добавляется в `memory-bank/prd/README.md` и достижим из navigation tree.
+
+Temporary intake PRD можно оставить как historical evidence или удалить по
+repository retention policy; в обоих случаях governed PRD должен сохранить
+нужную provenance. Не превращайте его в second active canonical owner.
+
+### 6. Добавить только подтверждённые durable artifacts
+
+Создавайте или обновляйте use cases только для устойчивых доказанных flows, а
+historical ADR — только для уже принятых и всё ещё влияющих решений. Не
+создавайте epics, feature packages или delivery plans, пока existing source
+явно не требует delivery work.
+
+### 7. Validate и trial
+
+Обновите README indexes и `derived_from` links. Запустите
+`memory-bank-cli lint` и `memory-bank-cli doctor`; если команда недоступна,
+запишите точную verification gap и выполните доступную проверку
+ссылок/структуры. Затем используйте adapted context в одной реальной task через
+подходящий flow до объявления rollout complete.
+
+## Product-type considerations
+
+Inventory и owner-документы conditional: не создавайте irrelevant artifacts.
+Для каждого unsupported dimension укажите `N/A` и короткую причину.
+
+### Web service
+
+Проверьте и адаптируйте, если применимо:
+
+- API/UI contracts, authentication/authorization, tenancy, rate limits и
+  compatibility commitments;
+- data stores, caches, asynchronous processing, webhooks, retention и
+  migration constraints;
+- deployment/rollback, health checks, contract/E2E testing, observability и
+  operational response.
+
+### CLI utility
+
+Проверьте и адаптируйте, если применимо:
+
+- commands/subcommands, flags, stdin/stdout/stderr contract, exit codes,
+  non-interactive behavior и shell completion;
+- installation/distribution, supported OS/architectures, update/uninstall;
+- config files, environment variables, filesystem effects, remote API
+  compatibility, golden tests и user-visible error compatibility.
+
+## Safety и change control
+
+- Не перезаписывайте existing docs, instructions или runtime code как часть
+  adaptation.
+- Ссылайтесь на external/legacy sources вместо indiscriminate copying; сохраняйте
+  их status и freshness caveats.
+- Выполняйте adaptation в reviewable change. Перечислите created, changed и
+  intentionally unadapted documents.
+- Назначьте follow-up trigger и owner для обновления Memory Bank при изменении
+  source code, operations или documented contracts.
+
+## Minimum rollout Definition of Done
+
+- [ ] Baseline `product/`, `domain/`, `engineering/` и `ops/` адаптированы из
+      evidence или явно отмечены gaps/`N/A`.
+- [ ] Intake PRD находится вне `memory-bank/`; governed/draft PRD имеет
+      корректные upstream dependencies и index route.
+- [ ] Все known gaps, conflicts и owner-pending facts имеют evidence и owner,
+      если он известен.
+- [ ] Use cases и historical ADRs созданы только при source evidence; лишние
+      delivery artifacts не созданы.
+- [ ] `memory-bank-cli lint` и `memory-bank-cli doctor` успешны либо
+      verification gap указан без заявления об успехе.
+- [ ] Adapted context испытан на одной real task через выбранный flow.
+- [ ] Reviewable change перечисляет created, changed и intentionally unadapted
+      documents, а также follow-up owner/triggers.
+
+## Copyable Codex prompt
+
+```text
+Это brownfield-репозиторий. До явной команды «установить Memory Bank» не
+открывай и не консультируй memory-bank/. Сначала прочитай repository
+instructions и исследуй только существующие README, docs, code, manifests,
+CI/CD, configuration, runbooks и historical ADR. Запиши evidence-backed intake
+PRD в ./brownfield-intake-prd.md: facts, sources, confidence, conflicts,
+assumptions, open questions и owner/freshness. Не выдумывай architecture или
+delivery plan. После discovery установи Memory Bank, адаптируй canonical owners
+из того же evidence, конвертируй intake в governed PRD и проверь
+memory-bank-cli lint/doctor.
+```