From 1648514576f3f78a5e2b01e344741e35bc60d1a3 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Wed, 22 Jul 2026 16:15:05 +0300 Subject: [PATCH 1/5] docs: add brownfield adaptation protocol --- README.md | 1 + docs/adoption.md | 55 +---- docs/brownfield-adaptation-protocol.md | 190 ++++++++++++++++++ memory-bank/features/FT-53/README.md | 38 ++++ memory-bank/features/FT-53/brief.md | 129 ++++++++++++ memory-bank/features/FT-53/decision-log.md | 93 +++++++++ .../features/FT-53/feature-review-report.md | 118 +++++++++++ .../features/FT-53/implementation-plan.md | 134 ++++++++++++ memory-bank/features/README.md | 6 + 9 files changed, 712 insertions(+), 52 deletions(-) create mode 100644 docs/brownfield-adaptation-protocol.md create mode 100644 memory-bank/features/FT-53/README.md create mode 100644 memory-bank/features/FT-53/brief.md create mode 100644 memory-bank/features/FT-53/decision-log.md create mode 100644 memory-bank/features/FT-53/feature-review-report.md create mode 100644 memory-bank/features/FT-53/implementation-plan.md diff --git a/README.md b/README.md index 37b678a..831e55a 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,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`](docs/memory-bank.md) | Для пользователей CLI и downstream CI | diff --git a/docs/adoption.md b/docs/adoption.md index 2e96923..c58e762 100644 --- a/docs/adoption.md +++ b/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 lint` проходит локально. +Не заменяйте protocol кратким inventory: порядок важен, потому что generic template не является источником project facts до завершения discovery. ## Начать новый проект (greenfield) @@ -84,7 +35,7 @@ codex --search \ Используйте 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). -Для первой адаптации можно использовать запрос: +После установки Memory Bank для первой адаптации можно использовать запрос: ```text Прочитай ./memory-bank/README.md и governance-ядро в ./memory-bank/dna/. diff --git a/docs/brownfield-adaptation-protocol.md b/docs/brownfield-adaptation-protocol.md new file mode 100644 index 0000000..5257dc5 --- /dev/null +++ b/docs/brownfield-adaptation-protocol.md @@ -0,0 +1,190 @@ +# Протокол адаптации 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 lint` и +`memory-bank 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 lint` и `memory-bank 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 и проверь lint/doctor. +``` diff --git a/memory-bank/features/FT-53/README.md b/memory-bank/features/FT-53/README.md new file mode 100644 index 0000000..ba72562 --- /dev/null +++ b/memory-bank/features/FT-53/README.md @@ -0,0 +1,38 @@ +--- +title: "FT-53: Brownfield Adaptation Protocol" +doc_kind: feature +doc_function: index +purpose: "Навигация по документации FT-53: protocol безопасной адаптации Memory Bank в существующем репозитории." +derived_from: + - ../../dna/governance.md + - brief.md +status: active +audience: humans_and_agents +--- + +# FT-53: Brownfield Adaptation Protocol + +## О разделе + +Сначала читай canonical [`brief.md`](brief.md): в нём находятся problem space, +requirements, validation profile и verify contract. Отдельный `design.md` не +создан: решение `DEC-53-01` в brief фиксирует, что feature меняет только +документацию и не требует solution-space owner. + +## Аннотированный индекс + +- [`brief.md`](brief.md) + Читать, когда нужно: понять scope, acceptance criteria и evidence contract + delivery-единицы. + +- [`decision-log.md`](decision-log.md) + Читать, когда нужно: проверить feature-local решения, их evidence и статус. + Не переопределяет requirements или execution sequence. + +- [`implementation-plan.md`](implementation-plan.md) + Читать, когда нужно: выполнить согласованные документальные изменения и + verification согласно canonical contract из brief. + +- [`feature-review-report.md`](feature-review-report.md) + Читать, когда нужно: проверить результаты ограниченного review-improve и + известный verification gap. Не является canonical owner feature facts. diff --git a/memory-bank/features/FT-53/brief.md b/memory-bank/features/FT-53/brief.md new file mode 100644 index 0000000..b21cb45 --- /dev/null +++ b/memory-bank/features/FT-53/brief.md @@ -0,0 +1,129 @@ +--- +title: "FT-53: Brownfield Adaptation Protocol" +doc_kind: feature +doc_function: canonical +purpose: "Canonical problem-space brief для отдельного protocol адаптации Memory Bank в существующем репозитории." +derived_from: + - ../../flows/feature.md + - ../../engineering/validation-profiles.md +status: active +delivery_status: in_progress +audience: humans_and_agents +must_not_define: + - implementation_sequence + - solution_space +--- + +# FT-53: Brownfield Adaptation Protocol + +## What + +### Problem + +Issue [#53](https://github.com/dapi/memory-bank/issues/53) отмечает, что +существующий раздел brownfield в [`../../../docs/adoption.md`](../../../docs/adoption.md) +описывает inventory и порядок заполнения, но не даёт исполнимого end-to-end +protocol, сопоставимого с greenfield protocol. Если агент начинает discovery +после установки или чтения generic `memory-bank/`, placeholders и generic rules +могут быть ошибочно приняты за project facts. + +### Outcome + +| Metric ID | Metric | Baseline | Target | Measurement method | +| --- | --- | --- | --- | --- | +| `MET-53-01` | Наличие исполнимого brownfield protocol | В `docs/adoption.md` есть только краткие guidance sections | Новый protocol описывает discovery, intake PRD, adaptation, conversion, validation и trial | Semantic review against `REQ-53-01`–`REQ-53-06` and `SC-53-01` | + +### Scope + +- `REQ-53-01` Создать generic protocol для адаптации Memory Bank в brownfield web services и CLI utilities и связать его с repository navigation. +- `REQ-53-02` Явно отделить pre-adaptation discovery от governed Memory Bank work: до установки/активации `memory-bank/` agent читает repository instructions и только существующие project sources, но не consults `memory-bank/`. +- `REQ-53-03` Определить временный evidence-backed intake PRD в `./brownfield-intake-prd.md` вне `memory-bank/`: required fields, lifecycle и запрет на invented architecture/delivery plan; затем описать его governed conversion в `memory-bank/prd/PRD-XXX-*.md` после adaptation upstream owners. +- `REQ-53-04` Определить conditional inventory и adaptation для web service и CLI, включая явное `N/A` с причиной для неприменимых dimensions. +- `REQ-53-05` Определить safety/migration rules, minimum rollout DoD, completion evidence и один real-task trial; не допускать копирования secrets, PII, tokens или internal endpoints. +- `REQ-53-06` Reconcile existing brownfield guidance с protocol и greenfield protocol без изменения runtime code, repository instructions или existing documentation кроме связанных navigation/guidance documents. + +### Non-Scope + +- `NS-53-01` Не адаптировать этот repository как downstream project и не создавать project-specific facts. +- `NS-53-02` Не изменять runtime code, CLI behavior, CI workflow или `memory-bank` validator. +- `NS-53-03` Не создавать delivery plans, feature packages, epics, use cases или historical ADR в downstream repository без evidence из его existing sources. + +### Constraints / Assumptions + +- `ASM-53-01` Issue #53 — authoritative source required outcome and acceptance criteria for this delivery-unit. +- `CON-53-01` Новый protocol остаётся generic: project-specific terminology, facts, secrets and internal endpoints в него не попадают. +- `CON-53-02` Existing `docs/adoption.md` и `docs/greenfield-integration-protocol.md` являются related canonical guidance; FT-53 must reconcile, rather than duplicate or contradict, their lifecycle boundaries. +- `DEC-53-01` Design required: no. Evidence: scope is a documentation-only protocol and links; no executable behavior, API/event/schema/config/release or architecture boundary changes are requested. Decision detail and FPF record: [`decision-log.md`](decision-log.md#dec-53-01-design-owner-not-required). +- `DEC-53-03` Default temporary intake location is `./brownfield-intake-prd.md`; it is explicit, generic and necessarily outside `memory-bank/`. Decision detail and FPF record: [`decision-log.md`](decision-log.md#dec-53-03-default-intake-location-is-the-repository-root). + +## Design Requirement Decision + +| Decision | Reason | Downstream owner | +| --- | --- | --- | +| `Design required: no` | `REQ-53-*` changes documentation guidance only; selected runtime solution, architecture coverage and contracts are out of scope. | `none` | + +## Artifact Routing Decision + +| Artifact | Decision | Trigger / reason | Route / owner | +| --- | --- | --- | --- | +| `decision-log.md` | selected | User requires a decision log within the feature; it records evidence-backed decisions without becoming a second canonical owner. | Feature-local decision record derived from `brief.md` | +| `design.md` | omitted | `DEC-53-01`: no solution-space trigger. | `none` | +| feature support artifacts and ADR | omitted | No runtime surface, UI, integration, architectural or reusable cross-feature decision is in scope. | `none` | + +## Validation Profile Decision + +| Profile | Triggers / rationale | Downgrade approval | +| --- | --- | --- | +| `documentation` | Only docs and repository navigation change; executable behavior, contracts, production config and release path remain unchanged (`NS-53-02`). | `none` | + +## Verify + +### Exit Criteria + +- `EC-53-01` Protocol exists, is reachable from root navigation and adoption guidance, and explicitly prohibits consulting `memory-bank/` during pre-adaptation discovery. +- `EC-53-02` Protocol specifies intake PRD fields, location, conversion and dependency rule; web-service/CLI inventory, `N/A` treatment, safety rules and rollout DoD are complete. +- `EC-53-03` Existing brownfield guidance and greenfield protocol have no lifecycle contradiction, and all changed docs pass applicable link/index validation or record a verification gap. + +### Traceability matrix + +| Requirement ID | Problem refs | Acceptance refs | Checks | Evidence IDs | +| --- | --- | --- | --- | --- | +| `REQ-53-01`, `REQ-53-02` | `ASM-53-01`, `CON-53-01` | `EC-53-01`, `SC-53-01` | `CHK-53-01`, `CHK-53-03` | `EVID-53-01`, `EVID-53-03` | +| `REQ-53-03`, `REQ-53-04`, `REQ-53-05` | `ASM-53-01`, `CON-53-01` | `EC-53-02`, `SC-53-02` | `CHK-53-01` | `EVID-53-01` | +| `REQ-53-06` | `CON-53-02` | `EC-53-03`, `SC-53-03` | `CHK-53-02`, `CHK-53-03` | `EVID-53-02`, `EVID-53-03` | + +### Acceptance Scenarios + +- `SC-53-01` A brownfield agent follows the protocol and completes pre-adaptation discovery without opening the generic or installed `memory-bank/`, then knows when to install and govern it. +- `SC-53-02` A web-service or CLI adaptation records only supported evidence, marks an unsupported dimension `N/A` with a reason, creates an intake PRD outside Memory Bank and converts it only after upstream owners are adapted. +- `SC-53-03` A reviewer can navigate from root/adoption docs to the protocol, compare its lifecycle with greenfield guidance, and run the documented validation commands without broken links or unindexed feature docs. + +### Checks + +| Check ID | Covers | How to check | Expected result | Evidence path | +| --- | --- | --- | --- | --- | +| `CHK-53-01` | `EC-53-01`, `EC-53-02`, `SC-53-01`, `SC-53-02` | Semantic read-through of protocol against `REQ-53-01`–`REQ-53-05` and issue #53. | Every required lifecycle, inventory, safety and DoD fact has one unambiguous owner in the protocol or linked canonical guidance. | `git diff -- docs/adoption.md docs/brownfield-adaptation-protocol.md README.md` | +| `CHK-53-02` | `EC-53-03`, `SC-53-03` | Compare brownfield protocol, adoption guidance and greenfield protocol for discovery/install/adaptation boundaries. | No document permits consulting `memory-bank/` before brownfield discovery; no conflicting lifecycle claim remains. | `git diff --check` plus reviewer read-through | +| `CHK-53-03` | `EC-53-01`, `EC-53-03`, `SC-53-03` | Run `memory-bank lint`; if unavailable, record the command failure and run `rg --files memory-bank` plus direct link inspection. | Lint passes, or the exact verification gap is recorded without claiming success. | Command output in review/PR evidence | + +### Test matrix + +| Check ID | Evidence IDs | Evidence path | +| --- | --- | --- | +| `CHK-53-01` | `EVID-53-01` | `git diff -- docs/adoption.md docs/brownfield-adaptation-protocol.md README.md` | +| `CHK-53-02` | `EVID-53-02` | `git diff --check` and reviewer read-through | +| `CHK-53-03` | `EVID-53-03` | `memory-bank lint` output or stated fallback gap | + +### Evidence + +- `EVID-53-01` Diff and semantic review show complete protocol coverage. +- `EVID-53-02` Diff-check and reconciliation read-through show no contradictory guidance. +- `EVID-53-03` Lint output, or an explicit unavailable-command verification gap with fallback evidence. + +### Evidence contract + +| Evidence ID | Artifact | Producer | Path contract | Reused by checks | +| --- | --- | --- | --- | --- | +| `EVID-53-01` | Changed-doc diff and reviewer notes | implementer / reviewer | PR or working-tree diff limited to changed documentation | `CHK-53-01` | +| `EVID-53-02` | Whitespace/link reconciliation result | implementer / reviewer | `git diff --check` output and review notes | `CHK-53-02` | +| `EVID-53-03` | Lint result or explicit verification-gap note | implementer | command output attached to PR/review | `CHK-53-03` | diff --git a/memory-bank/features/FT-53/decision-log.md b/memory-bank/features/FT-53/decision-log.md new file mode 100644 index 0000000..43583b7 --- /dev/null +++ b/memory-bank/features/FT-53/decision-log.md @@ -0,0 +1,93 @@ +--- +title: "FT-53: Decision Log" +doc_kind: feature +doc_function: decision_log +purpose: "Feature-local log of evidence-backed FT-53 decisions; it does not own requirements, solution space or execution sequencing." +derived_from: + - brief.md +status: active +audience: humans_and_agents +must_not_define: + - ft_53_problem_space + - ft_53_selected_design + - ft_53_execution_sequence +--- + +# FT-53: Decision Log + +## Decision records + +### DEC-53-01: Design owner not required + +- **Status:** accepted +- **Decision:** Do not create `design.md` for FT-53. +- **Question:** Does the requested brownfield protocol require a separate + solution-space owner before an implementation plan can be written? +- **Evidence:** Issue #53 requests generic documentation: a protocol, links, + lifecycle guidance, inventory, safety rules and validation. Its acceptance + criteria do not request a runtime, API, event, schema, configuration, + deployment or architectural change. `brief.md` constrains the feature to + documentation and excludes those changes in `NS-53-02`. +- **FPF reasoning:** The problem-space owner (`brief.md`) owns what must be + documented and verified. A solution-space owner is required only if the + package must decide an architecture, contract, invariant, failure mode or + rollout semantics. The evidence places none of those objects in this + feature's bounded context; adding `design.md` would create an empty owner and + blur the problem/execution boundary. Therefore the smallest coherent package + is brief + decision log + plan. +- **Alternatives considered:** (1) create `design.md` with the protocol outline; + rejected because that duplicates requirements as solution facts. (2) record + the outline only in the plan; rejected because the plan must not own scope. +- **Consequences:** `implementation-plan.md` may sequence documentation edits, + but must promote any newly discovered runtime/contract or architectural + decision to the appropriate owner before planning it. + +### DEC-53-02: Intake PRD stays outside Memory Bank until upstream adaptation + +- **Status:** accepted +- **Decision:** The protocol will require a temporary intake PRD outside + `memory-bank/` during pre-adaptation discovery, then govern/import it only + after the relevant baseline owners are adapted. +- **Question:** Where can discovery facts be safely recorded before Memory Bank + is allowed to influence discovery? +- **Evidence:** Issue #53 explicitly prescribes an evidence-backed intake PRD + outside `memory-bank/`, followed by conversion into `memory-bank/prd/` whose + `derived_from` links point only to already adapted upstream owners. It also + explicitly prohibits consulting `memory-bank/` during pre-adaptation + discovery. +- **FPF reasoning:** Treat pre-adaptation discovery and governed Memory Bank as + different bounded contexts. A temporary artifact can preserve evidence and + uncertainty without becoming an authority of the not-yet-installed governance + system. After owners exist, conversion creates the governed dependency graph; + collapsing the stages would let generic placeholders contaminate project + knowledge. +- **Consequences:** The protocol must specify a clearly named non-`memory-bank/` + location and preserve source references, confidence, conflicts and open + questions through conversion. + +### DEC-53-03: Default intake location is the repository root + +- **Status:** accepted +- **Decision:** The protocol's temporary intake PRD path is + `./brownfield-intake-prd.md`. +- **Question:** What exact location can the generic protocol prescribe without + assuming that a downstream repository already has a `docs/` directory or any + governed Memory Bank structure? +- **Evidence:** Issue #53 requires the protocol to define an intake PRD + location outside `memory-bank/`; pre-adaptation discovery occurs before + Memory Bank is consulted or installed. The issue does not establish any + repository-specific documentation directory. +- **FPF reasoning:** The pre-adaptation and governed contexts must remain + separate (`DEC-53-02`). The repository root is the only path boundary present + in every repository without importing an unproven convention; the selected + filename is explicit and cannot be mistaken for an artifact inside + `memory-bank/`. This supplies a deterministic hand-off while making no claim + about downstream documentation layout. +- **Alternatives considered:** `docs/brownfield-intake-prd.md` is rejected: a + `docs/` directory is not guaranteed by the evidence. An unspecified + non-`memory-bank/` path is rejected: it fails the issue's explicit location + requirement and weakens the hand-off. +- **Consequences:** The protocol will use this default path. A repository may + retain an existing local convention only when it records the chosen alternate + path and preserves all required intake fields and the outside-`memory-bank/` + boundary. diff --git a/memory-bank/features/FT-53/feature-review-report.md b/memory-bank/features/FT-53/feature-review-report.md new file mode 100644 index 0000000..edab805 --- /dev/null +++ b/memory-bank/features/FT-53/feature-review-report.md @@ -0,0 +1,118 @@ +--- +title: "FT-53: Feature Review Report" +doc_kind: feature +doc_function: reference +purpose: "Результат ограниченного review-improve комплекта FT-53; фиксирует findings, их disposition и verification evidence без переопределения canonical owners." +derived_from: + - brief.md + - decision-log.md + - implementation-plan.md +status: active +audience: humans_and_agents +must_not_define: + - ft_53_problem_space + - ft_53_selected_design + - ft_53_execution_sequence +--- + +# FT-53: Feature Review Report + +## Cycle 1 + +### Review summary + +Reviewed the complete package: `README.md`, canonical `brief.md`, +`decision-log.md` and `implementation-plan.md`, plus the explicit related +guidance in `docs/adoption.md` and `docs/greenfield-integration-protocol.md`. +The package has one canonical problem owner, no required design owner, an +execution plan derived from the brief, and complete `REQ -> SC/EC -> CHK -> +EVID` traceability. No contradiction between the decision log, brief and plan +was found. + +### Findings + +| ID | Priority | Finding | Disposition | +| --- | --- | --- | --- | +| `I-53-01` | important | Feature Flow requires the source issue to link back to `brief.md` and downstream feature documents; the package had only the forward issue link. | Closed: issue [#53 comment](https://github.com/dapi/memory-bank/issues/53#issuecomment-5046125234) links both `brief.md` and `implementation-plan.md`. | +| `I-53-02` | important | `implementation-plan.md` declares `EVID-53-09` at `feature-review-report.md`, but the referenced review artifact did not exist. | Closed by this document and its route from package `README.md`. | + +### Open questions closed through FPF + +- `DEC-53-01` in [`decision-log.md`](decision-log.md#dec-53-01-design-owner-not-required): no `design.md`. The issue limits the feature to documentation and navigation; no architecture, contract or runtime decision is needed. +- `DEC-53-02` in [`decision-log.md`](decision-log.md#dec-53-02-intake-prd-stays-outside-memory-bank-until-upstream-adaptation): keep the intake PRD outside `memory-bank/` until evidence-backed upstream owners exist. This follows the explicit staged lifecycle in issue #53 and prevents generic-template facts from entering discovery. + +### Changes made + +- Created and indexed this report. +- Added the tracker-to-feature links required by Feature Flow. + +### Human gate + +No. Issue #53 supplies unambiguous requirements for both decisions; no missing +fact materially changes FT-53 scope or acceptance. + +## Cycle 2 + +### Review summary + +Re-reviewed the package after cycle-1 corrections, including frontmatter, +`derived_from` links, package index reachability, canonical-owner boundaries, +decision/plan consistency and the verify chain. The Go CLI completed a full +Memory Bank audit successfully. + +### Findings + +| ID | Priority | Finding | Disposition | +| --- | --- | --- | --- | +| `I-53-03` | important | `REQ-53-03` required an exact temporary intake-PRD location, but the brief and plan only said «outside `memory-bank/`». | Closed by `DEC-53-03`: the generic default is `./brownfield-intake-prd.md`; the requirement and plan now reuse that canonical decision. | + +### Open questions closed through FPF + +- `DEC-53-03` in [`decision-log.md`](decision-log.md#dec-53-03-default-intake-location-is-the-repository-root): the repository root is the only evidence-independent path boundary; a `docs/` directory cannot be assumed before adaptation. The decision remains generic and preserves the mandatory outside-`memory-bank/` boundary. + +### Changes made + +- Added the exact intake location to `REQ-53-03`, decision record and plan precondition/step. +- Ran `go run ./cmd/memory-bank lint` from `tools/`: passed. + +### Human gate + +No. The location is a generic protocol convention whose selection follows the +issue's mandatory boundary and does not assert a downstream project fact. + +## Cycle 3 + +### Review summary + +Reviewed the final package for canonical-owner separation, decision-log/brief/ +plan agreement, frontmatter and `derived_from` integrity, package and root +index reachability, all `REQ -> SC/EC -> CHK -> EVID` paths, and references to +the related adoption and greenfield guidance. No `critical` or `important` +finding remains; the review-improve loop stops early after three cycles. + +### Findings + +None at `critical` or `important` priority. + +### Open questions closed through FPF + +None. All feature-material decisions are already recorded as `DEC-53-01` to +`DEC-53-03` in [`decision-log.md`](decision-log.md). + +### Changes made + +None; this was a convergence review. + +### Human gate + +No. + +## Verification status + +- `git diff --check`: passed during cycle 1. +- `go run ./cmd/memory-bank lint` from `tools/`: passed. The installed + `memory-bank` executable remains unavailable, but the same repository CLI + command completed the required lint audit successfully. +- `go test -count=1 -race ./...` from `tools/`: passed. +- `go vet ./...` from `tools/`: passed. +- `git diff --check`: passed. diff --git a/memory-bank/features/FT-53/implementation-plan.md b/memory-bank/features/FT-53/implementation-plan.md new file mode 100644 index 0000000..5371258 --- /dev/null +++ b/memory-bank/features/FT-53/implementation-plan.md @@ -0,0 +1,134 @@ +--- +title: "FT-53: Implementation Plan" +doc_kind: feature +doc_function: derived +purpose: "Execution plan for the brownfield adaptation protocol without redefining FT-53 problem-space facts or validation profile." +derived_from: + - brief.md + - decision-log.md +status: active +audience: humans_and_agents +must_not_define: + - ft_53_scope + - ft_53_selected_design + - ft_53_acceptance_criteria + - ft_53_blocker_state + - ft_53_validation_profile +--- + +# FT-53: Implementation Plan + +## Goal + +Deliver the documentation outcome defined by `REQ-53-01`–`REQ-53-06`, retaining +`brief.md` as the canonical owner of requirements and verification. + +## Grounding / Support References + +| Document | Role in this plan | Facts reused | Conflict action | +| --- | --- | --- | --- | +| [`brief.md`](brief.md) | Canonical problem, validation and verify owner | `REQ-53-*`, `SC-53-*`, `CHK-53-*`, `EVID-53-*` | Update brief first | +| [`decision-log.md`](decision-log.md) | Feature-local decision evidence | `DEC-53-01`, `DEC-53-02` | Update decision log and brief if problem-space facts change | +| [`../../../docs/adoption.md`](../../../docs/adoption.md) | Existing brownfield guidance to reconcile | Current inventory, order and readiness sections | Update canonical guidance rather than duplicate it | +| [`../../../docs/greenfield-integration-protocol.md`](../../../docs/greenfield-integration-protocol.md) | Adjacent lifecycle reference | Existing install/adaptation ordering | Escalate lifecycle conflict to brief before edits | + +`design.md`, support artifacts, contracts, diagrams and ADRs: `none`, per +`DEC-53-01` in [`brief.md`](brief.md#design-requirement-decision). + +## Current State / Reference Points + +| Path / module | Current role | Why relevant | Reuse / mirror | +| --- | --- | --- | --- | +| `docs/adoption.md` | Entry guidance for brownfield and greenfield adoption | Must link to the dedicated protocol and no longer carry contradictory lifecycle detail | Keep it as concise routing/summary guidance | +| `docs/greenfield-integration-protocol.md` | Executable neighboring protocol | Defines the expected level of lifecycle detail and source-evidence discipline | Mirror structure where applicable, not greenfield-specific facts | +| `README.md` | Root documentation navigation | Must make the new protocol discoverable | Add one annotated link | + +## Test Strategy + +Validation profile is `documentation`, selected only in [`brief.md`](brief.md#validation-profile-decision). + +| Test surface | Canonical refs | Planned coverage | Required local commands | Manual-only gap / justification | +| --- | --- | --- | --- | --- | +| Protocol completeness | `REQ-53-01`–`REQ-53-05`, `CHK-53-01` | Targeted semantic read-through | `git diff -- docs/adoption.md docs/brownfield-adaptation-protocol.md README.md` | Reviewer verifies prose meaning | +| Guidance reconciliation | `REQ-53-06`, `CHK-53-02` | Whitespace and lifecycle read-through | `git diff --check` | Reviewer compares lifecycle boundaries | +| Memory Bank navigation | `CHK-53-03` | Links and indexes | `memory-bank lint` | If unavailable, state exact gap and use brief fallback | + +## Open Questions / Ambiguities + +none. `DEC-53-01` and `DEC-53-02` are closed from issue evidence in +[`decision-log.md`](decision-log.md); no open question blocks planning. + +## Environment Contract + +| Area | Contract | Used by | Failure symptom | +| --- | --- | --- | --- | +| setup | Run from repository root with Git available | `STEP-53-01`–`STEP-53-04` | Paths or diff evidence cannot be resolved | +| test | `memory-bank lint` is the primary navigation check; `git diff --check` checks whitespace | `CHK-53-02`, `CHK-53-03` | Missing command produces a stated verification gap, not a pass | +| access / network / secrets | No secrets, external access or runtime environment is required | all steps | Any request to copy sensitive project data stops the work and triggers scope escalation | + +## Preconditions + +| Precondition ID | Canonical ref | Required state | Used by steps | Blocks start | +| --- | --- | --- | --- | --- | +| `PRE-53-01` | `DEC-53-01` | Feature remains documentation-only | `STEP-53-01`–`STEP-53-04` | yes | +| `PRE-53-02` | `DEC-53-02`, `DEC-53-03` | Intake PRD lifecycle remains evidence-backed, staged and starts at `./brownfield-intake-prd.md` | `STEP-53-01` | yes | + +## Design Realization Mapping + +Not applicable: `Design required: no` in [`brief.md`](brief.md#design-requirement-decision). + +## Workstreams + +| Workstream | Implements | Result | Owner | Dependencies | +| --- | --- | --- | --- | --- | +| `WS-53-01` | `REQ-53-01`–`REQ-53-05` | Dedicated generic brownfield protocol | agent | `PRE-53-01`, `PRE-53-02` | +| `WS-53-02` | `REQ-53-06` | Reconciled adoption/root navigation | agent | `WS-53-01` | +| `WS-53-03` | `CHK-53-01`–`CHK-53-03` | Verification evidence or explicit gap | agent / reviewer | `WS-53-01`, `WS-53-02` | + +## Approval Gates + +None. The `documentation` validation profile requires ordinary review only; +any scope expansion to runtime, secrets or project-specific facts must stop and +be escalated under `STOP-53-01`. + +## Work Sequence + +| Step ID | Actor | Implements | Goal | Touchpoints | Artifact | Verifies | Evidence IDs | Check command / procedure | Blocked by | Needs approval | Escalate if | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| `STEP-53-01` | agent | `REQ-53-01`–`REQ-53-05` | Write protocol with staged discovery, intake at `./brownfield-intake-prd.md`, adaptation, conversion, conditional inventory, safety and DoD | `docs/brownfield-adaptation-protocol.md` | New protocol | `CHK-53-01` | `EVID-53-01` | Compare every section with brief and issue | `PRE-53-01`, `PRE-53-02` | none | An unresolvable conflict with canonical guidance appears | +| `STEP-53-02` | agent | `REQ-53-06` | Replace detailed brownfield lifecycle in adoption docs with concise route; link root navigation | `docs/adoption.md`, `README.md` | Reachable guidance | `CHK-53-02` | `EVID-53-02` | Read all three lifecycle documents together | `STEP-53-01` | none | A required change affects unrelated guidance | +| `STEP-53-03` | agent | `CHK-53-01`, `CHK-53-02` | Run documentation integrity checks | changed docs | Review result | `CHK-53-01`, `CHK-53-02` | `EVID-53-01`, `EVID-53-02` | `git diff --check`; semantic read-through | `STEP-53-02` | none | A requirement cannot be evidenced from issue or docs | +| `STEP-53-04` | agent | `CHK-53-03` | Verify Memory Bank links/indexes and record result | `memory-bank/` | Lint result or gap | `CHK-53-03` | `EVID-53-03` | `memory-bank lint`, otherwise fallback in brief | `STEP-53-02` | none | Lint reports unresolved issue outside feature scope | + +## Checkpoints + +| Checkpoint ID | Refs | Condition | Evidence IDs | +| --- | --- | --- | --- | +| `CP-53-01` | `STEP-53-01`, `CHK-53-01` | All required protocol sections trace to `REQ-53-*` IDs | `EVID-53-01` | +| `CP-53-02` | `STEP-53-02`, `CHK-53-02` | Adoption, root and greenfield paths have compatible lifecycle boundaries | `EVID-53-02` | +| `CP-53-03` | `STEP-53-04`, `CHK-53-03` | Lint passes or exact verification gap is captured | `EVID-53-03` | + +## Execution Risks + +| Risk ID | Risk | Impact | Mitigation | Trigger | +| --- | --- | --- | --- | --- | +| `ER-53-01` | Protocol duplicates and drifts from adoption guidance | Conflicting instructions | Keep adoption as short routing and protocol as detailed lifecycle owner | Same lifecycle rule has different wording/order | +| `ER-53-02` | Generic guidance asserts downstream facts | Unsafe adaptation | Require source references, confidence and explicit unknown/conflict records | Draft names an unsupported product, endpoint, secret or owner | + +## Stop Conditions / Fallback + +| Stop ID | Related refs | Trigger | Immediate action | Safe fallback state | +| --- | --- | --- | --- | --- | +| `STOP-53-01` | `CON-53-01`, `NS-53-01`, `NS-53-02` | Edit needs project-specific facts, secrets, runtime behavior or unproven lifecycle choice | Stop and request human decision with evidence/options | Keep scoped documentation draft; do not claim completion | + +## Plan-local Evidence + +| Evidence ID | Artifact | Producer | Path contract | Reused by checkpoints | +| --- | --- | --- | --- | --- | +| `EVID-53-09` | Feature-pack review report | documentation quality agent | `memory-bank/features/FT-53/feature-review-report.md` | final handoff | + +## Ready for Acceptance + +- All workstreams and checkpoints are complete. +- `CHK-53-01`–`CHK-53-03` have evidence or the permitted verification gap is explicit. +- Final acceptance follows [`brief.md`](brief.md#verify), not this plan. diff --git a/memory-bank/features/README.md b/memory-bank/features/README.md index b1aee59..6d837b5 100644 --- a/memory-bank/features/README.md +++ b/memory-bank/features/README.md @@ -26,6 +26,12 @@ audience: humans_and_agents - Если feature реализует или существенно меняет устойчивый сценарий проекта, она должна ссылаться на соответствующий `UC-*` из [`../use-cases/README.md`](../use-cases/README.md). - В шаблонном репозитории этот каталог может быть пустым. Это нормально. +## Packages + +- [`FT-53/`](FT-53/) + Protocol безопасной адаптации Memory Bank в существующем (brownfield) + репозитории. + ## Naming - Базовый формат: `FT-XXX/` From 0708294e6e552576d10ec617c56417430fb6e64b Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Wed, 22 Jul 2026 16:16:22 +0300 Subject: [PATCH 2/5] docs: complete brownfield feature evidence --- memory-bank/features/FT-53/brief.md | 2 +- .../features/FT-53/feature-review-report.md | 24 +++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/memory-bank/features/FT-53/brief.md b/memory-bank/features/FT-53/brief.md index b21cb45..d6a74ee 100644 --- a/memory-bank/features/FT-53/brief.md +++ b/memory-bank/features/FT-53/brief.md @@ -7,7 +7,7 @@ derived_from: - ../../flows/feature.md - ../../engineering/validation-profiles.md status: active -delivery_status: in_progress +delivery_status: done audience: humans_and_agents must_not_define: - implementation_sequence diff --git a/memory-bank/features/FT-53/feature-review-report.md b/memory-bank/features/FT-53/feature-review-report.md index edab805..990827f 100644 --- a/memory-bank/features/FT-53/feature-review-report.md +++ b/memory-bank/features/FT-53/feature-review-report.md @@ -116,3 +116,27 @@ No. - `go test -count=1 -race ./...` from `tools/`: passed. - `go vet ./...` from `tools/`: passed. - `git diff --check`: passed. + +## Cycle 4: Delivery convergence + +### Review summary + +Reviewed the implemented change against `REQ-53-01`–`REQ-53-06` and issue #53. +`docs/brownfield-adaptation-protocol.md` owns the detailed lifecycle; root +navigation and `docs/adoption.md` route to it without retaining a contradictory +copy. The protocol preserves the pre-adaptation boundary, intake provenance, +conditional web-service/CLI coverage, safety rules, rollout DoD and copyable +prompt. No critical or important finding remains. + +### Evidence + +- `EVID-53-01`: semantic review of the protocol against the brief and issue. +- `EVID-53-02`: reconciliation read-through plus `git diff --check`. +- `EVID-53-03`: `go run ./cmd/memory-bank lint` and + `go run ./cmd/memory-bank doctor` from `tools/` both completed successfully. +- Supporting repository checks: `go test -count=1 -race ./...` and + `go vet ./...` from `tools/` completed successfully. + +### Human gate + +No. From 99712e02c7ea8693341dd2f5eed798b55055ad85 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Wed, 22 Jul 2026 16:17:46 +0300 Subject: [PATCH 3/5] docs: archive completed feature plan --- memory-bank/features/FT-53/implementation-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/memory-bank/features/FT-53/implementation-plan.md b/memory-bank/features/FT-53/implementation-plan.md index 5371258..6acbb94 100644 --- a/memory-bank/features/FT-53/implementation-plan.md +++ b/memory-bank/features/FT-53/implementation-plan.md @@ -6,7 +6,7 @@ purpose: "Execution plan for the brownfield adaptation protocol without redefini derived_from: - brief.md - decision-log.md -status: active +status: archived audience: humans_and_agents must_not_define: - ft_53_scope From ec85586d1d89b83270fe1db372088e8f83d8f421 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Thu, 23 Jul 2026 18:14:54 +0300 Subject: [PATCH 4/5] docs: keep delivery records out of template --- memory-bank/features/FT-53/README.md | 38 ----- memory-bank/features/FT-53/brief.md | 129 ---------------- memory-bank/features/FT-53/decision-log.md | 93 ------------ .../features/FT-53/feature-review-report.md | 142 ------------------ .../features/FT-53/implementation-plan.md | 134 ----------------- memory-bank/features/README.md | 6 - 6 files changed, 542 deletions(-) delete mode 100644 memory-bank/features/FT-53/README.md delete mode 100644 memory-bank/features/FT-53/brief.md delete mode 100644 memory-bank/features/FT-53/decision-log.md delete mode 100644 memory-bank/features/FT-53/feature-review-report.md delete mode 100644 memory-bank/features/FT-53/implementation-plan.md diff --git a/memory-bank/features/FT-53/README.md b/memory-bank/features/FT-53/README.md deleted file mode 100644 index ba72562..0000000 --- a/memory-bank/features/FT-53/README.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "FT-53: Brownfield Adaptation Protocol" -doc_kind: feature -doc_function: index -purpose: "Навигация по документации FT-53: protocol безопасной адаптации Memory Bank в существующем репозитории." -derived_from: - - ../../dna/governance.md - - brief.md -status: active -audience: humans_and_agents ---- - -# FT-53: Brownfield Adaptation Protocol - -## О разделе - -Сначала читай canonical [`brief.md`](brief.md): в нём находятся problem space, -requirements, validation profile и verify contract. Отдельный `design.md` не -создан: решение `DEC-53-01` в brief фиксирует, что feature меняет только -документацию и не требует solution-space owner. - -## Аннотированный индекс - -- [`brief.md`](brief.md) - Читать, когда нужно: понять scope, acceptance criteria и evidence contract - delivery-единицы. - -- [`decision-log.md`](decision-log.md) - Читать, когда нужно: проверить feature-local решения, их evidence и статус. - Не переопределяет requirements или execution sequence. - -- [`implementation-plan.md`](implementation-plan.md) - Читать, когда нужно: выполнить согласованные документальные изменения и - verification согласно canonical contract из brief. - -- [`feature-review-report.md`](feature-review-report.md) - Читать, когда нужно: проверить результаты ограниченного review-improve и - известный verification gap. Не является canonical owner feature facts. diff --git a/memory-bank/features/FT-53/brief.md b/memory-bank/features/FT-53/brief.md deleted file mode 100644 index d6a74ee..0000000 --- a/memory-bank/features/FT-53/brief.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "FT-53: Brownfield Adaptation Protocol" -doc_kind: feature -doc_function: canonical -purpose: "Canonical problem-space brief для отдельного protocol адаптации Memory Bank в существующем репозитории." -derived_from: - - ../../flows/feature.md - - ../../engineering/validation-profiles.md -status: active -delivery_status: done -audience: humans_and_agents -must_not_define: - - implementation_sequence - - solution_space ---- - -# FT-53: Brownfield Adaptation Protocol - -## What - -### Problem - -Issue [#53](https://github.com/dapi/memory-bank/issues/53) отмечает, что -существующий раздел brownfield в [`../../../docs/adoption.md`](../../../docs/adoption.md) -описывает inventory и порядок заполнения, но не даёт исполнимого end-to-end -protocol, сопоставимого с greenfield protocol. Если агент начинает discovery -после установки или чтения generic `memory-bank/`, placeholders и generic rules -могут быть ошибочно приняты за project facts. - -### Outcome - -| Metric ID | Metric | Baseline | Target | Measurement method | -| --- | --- | --- | --- | --- | -| `MET-53-01` | Наличие исполнимого brownfield protocol | В `docs/adoption.md` есть только краткие guidance sections | Новый protocol описывает discovery, intake PRD, adaptation, conversion, validation и trial | Semantic review against `REQ-53-01`–`REQ-53-06` and `SC-53-01` | - -### Scope - -- `REQ-53-01` Создать generic protocol для адаптации Memory Bank в brownfield web services и CLI utilities и связать его с repository navigation. -- `REQ-53-02` Явно отделить pre-adaptation discovery от governed Memory Bank work: до установки/активации `memory-bank/` agent читает repository instructions и только существующие project sources, но не consults `memory-bank/`. -- `REQ-53-03` Определить временный evidence-backed intake PRD в `./brownfield-intake-prd.md` вне `memory-bank/`: required fields, lifecycle и запрет на invented architecture/delivery plan; затем описать его governed conversion в `memory-bank/prd/PRD-XXX-*.md` после adaptation upstream owners. -- `REQ-53-04` Определить conditional inventory и adaptation для web service и CLI, включая явное `N/A` с причиной для неприменимых dimensions. -- `REQ-53-05` Определить safety/migration rules, minimum rollout DoD, completion evidence и один real-task trial; не допускать копирования secrets, PII, tokens или internal endpoints. -- `REQ-53-06` Reconcile existing brownfield guidance с protocol и greenfield protocol без изменения runtime code, repository instructions или existing documentation кроме связанных navigation/guidance documents. - -### Non-Scope - -- `NS-53-01` Не адаптировать этот repository как downstream project и не создавать project-specific facts. -- `NS-53-02` Не изменять runtime code, CLI behavior, CI workflow или `memory-bank` validator. -- `NS-53-03` Не создавать delivery plans, feature packages, epics, use cases или historical ADR в downstream repository без evidence из его existing sources. - -### Constraints / Assumptions - -- `ASM-53-01` Issue #53 — authoritative source required outcome and acceptance criteria for this delivery-unit. -- `CON-53-01` Новый protocol остаётся generic: project-specific terminology, facts, secrets and internal endpoints в него не попадают. -- `CON-53-02` Existing `docs/adoption.md` и `docs/greenfield-integration-protocol.md` являются related canonical guidance; FT-53 must reconcile, rather than duplicate or contradict, their lifecycle boundaries. -- `DEC-53-01` Design required: no. Evidence: scope is a documentation-only protocol and links; no executable behavior, API/event/schema/config/release or architecture boundary changes are requested. Decision detail and FPF record: [`decision-log.md`](decision-log.md#dec-53-01-design-owner-not-required). -- `DEC-53-03` Default temporary intake location is `./brownfield-intake-prd.md`; it is explicit, generic and necessarily outside `memory-bank/`. Decision detail and FPF record: [`decision-log.md`](decision-log.md#dec-53-03-default-intake-location-is-the-repository-root). - -## Design Requirement Decision - -| Decision | Reason | Downstream owner | -| --- | --- | --- | -| `Design required: no` | `REQ-53-*` changes documentation guidance only; selected runtime solution, architecture coverage and contracts are out of scope. | `none` | - -## Artifact Routing Decision - -| Artifact | Decision | Trigger / reason | Route / owner | -| --- | --- | --- | --- | -| `decision-log.md` | selected | User requires a decision log within the feature; it records evidence-backed decisions without becoming a second canonical owner. | Feature-local decision record derived from `brief.md` | -| `design.md` | omitted | `DEC-53-01`: no solution-space trigger. | `none` | -| feature support artifacts and ADR | omitted | No runtime surface, UI, integration, architectural or reusable cross-feature decision is in scope. | `none` | - -## Validation Profile Decision - -| Profile | Triggers / rationale | Downgrade approval | -| --- | --- | --- | -| `documentation` | Only docs and repository navigation change; executable behavior, contracts, production config and release path remain unchanged (`NS-53-02`). | `none` | - -## Verify - -### Exit Criteria - -- `EC-53-01` Protocol exists, is reachable from root navigation and adoption guidance, and explicitly prohibits consulting `memory-bank/` during pre-adaptation discovery. -- `EC-53-02` Protocol specifies intake PRD fields, location, conversion and dependency rule; web-service/CLI inventory, `N/A` treatment, safety rules and rollout DoD are complete. -- `EC-53-03` Existing brownfield guidance and greenfield protocol have no lifecycle contradiction, and all changed docs pass applicable link/index validation or record a verification gap. - -### Traceability matrix - -| Requirement ID | Problem refs | Acceptance refs | Checks | Evidence IDs | -| --- | --- | --- | --- | --- | -| `REQ-53-01`, `REQ-53-02` | `ASM-53-01`, `CON-53-01` | `EC-53-01`, `SC-53-01` | `CHK-53-01`, `CHK-53-03` | `EVID-53-01`, `EVID-53-03` | -| `REQ-53-03`, `REQ-53-04`, `REQ-53-05` | `ASM-53-01`, `CON-53-01` | `EC-53-02`, `SC-53-02` | `CHK-53-01` | `EVID-53-01` | -| `REQ-53-06` | `CON-53-02` | `EC-53-03`, `SC-53-03` | `CHK-53-02`, `CHK-53-03` | `EVID-53-02`, `EVID-53-03` | - -### Acceptance Scenarios - -- `SC-53-01` A brownfield agent follows the protocol and completes pre-adaptation discovery without opening the generic or installed `memory-bank/`, then knows when to install and govern it. -- `SC-53-02` A web-service or CLI adaptation records only supported evidence, marks an unsupported dimension `N/A` with a reason, creates an intake PRD outside Memory Bank and converts it only after upstream owners are adapted. -- `SC-53-03` A reviewer can navigate from root/adoption docs to the protocol, compare its lifecycle with greenfield guidance, and run the documented validation commands without broken links or unindexed feature docs. - -### Checks - -| Check ID | Covers | How to check | Expected result | Evidence path | -| --- | --- | --- | --- | --- | -| `CHK-53-01` | `EC-53-01`, `EC-53-02`, `SC-53-01`, `SC-53-02` | Semantic read-through of protocol against `REQ-53-01`–`REQ-53-05` and issue #53. | Every required lifecycle, inventory, safety and DoD fact has one unambiguous owner in the protocol or linked canonical guidance. | `git diff -- docs/adoption.md docs/brownfield-adaptation-protocol.md README.md` | -| `CHK-53-02` | `EC-53-03`, `SC-53-03` | Compare brownfield protocol, adoption guidance and greenfield protocol for discovery/install/adaptation boundaries. | No document permits consulting `memory-bank/` before brownfield discovery; no conflicting lifecycle claim remains. | `git diff --check` plus reviewer read-through | -| `CHK-53-03` | `EC-53-01`, `EC-53-03`, `SC-53-03` | Run `memory-bank lint`; if unavailable, record the command failure and run `rg --files memory-bank` plus direct link inspection. | Lint passes, or the exact verification gap is recorded without claiming success. | Command output in review/PR evidence | - -### Test matrix - -| Check ID | Evidence IDs | Evidence path | -| --- | --- | --- | -| `CHK-53-01` | `EVID-53-01` | `git diff -- docs/adoption.md docs/brownfield-adaptation-protocol.md README.md` | -| `CHK-53-02` | `EVID-53-02` | `git diff --check` and reviewer read-through | -| `CHK-53-03` | `EVID-53-03` | `memory-bank lint` output or stated fallback gap | - -### Evidence - -- `EVID-53-01` Diff and semantic review show complete protocol coverage. -- `EVID-53-02` Diff-check and reconciliation read-through show no contradictory guidance. -- `EVID-53-03` Lint output, or an explicit unavailable-command verification gap with fallback evidence. - -### Evidence contract - -| Evidence ID | Artifact | Producer | Path contract | Reused by checks | -| --- | --- | --- | --- | --- | -| `EVID-53-01` | Changed-doc diff and reviewer notes | implementer / reviewer | PR or working-tree diff limited to changed documentation | `CHK-53-01` | -| `EVID-53-02` | Whitespace/link reconciliation result | implementer / reviewer | `git diff --check` output and review notes | `CHK-53-02` | -| `EVID-53-03` | Lint result or explicit verification-gap note | implementer | command output attached to PR/review | `CHK-53-03` | diff --git a/memory-bank/features/FT-53/decision-log.md b/memory-bank/features/FT-53/decision-log.md deleted file mode 100644 index 43583b7..0000000 --- a/memory-bank/features/FT-53/decision-log.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "FT-53: Decision Log" -doc_kind: feature -doc_function: decision_log -purpose: "Feature-local log of evidence-backed FT-53 decisions; it does not own requirements, solution space or execution sequencing." -derived_from: - - brief.md -status: active -audience: humans_and_agents -must_not_define: - - ft_53_problem_space - - ft_53_selected_design - - ft_53_execution_sequence ---- - -# FT-53: Decision Log - -## Decision records - -### DEC-53-01: Design owner not required - -- **Status:** accepted -- **Decision:** Do not create `design.md` for FT-53. -- **Question:** Does the requested brownfield protocol require a separate - solution-space owner before an implementation plan can be written? -- **Evidence:** Issue #53 requests generic documentation: a protocol, links, - lifecycle guidance, inventory, safety rules and validation. Its acceptance - criteria do not request a runtime, API, event, schema, configuration, - deployment or architectural change. `brief.md` constrains the feature to - documentation and excludes those changes in `NS-53-02`. -- **FPF reasoning:** The problem-space owner (`brief.md`) owns what must be - documented and verified. A solution-space owner is required only if the - package must decide an architecture, contract, invariant, failure mode or - rollout semantics. The evidence places none of those objects in this - feature's bounded context; adding `design.md` would create an empty owner and - blur the problem/execution boundary. Therefore the smallest coherent package - is brief + decision log + plan. -- **Alternatives considered:** (1) create `design.md` with the protocol outline; - rejected because that duplicates requirements as solution facts. (2) record - the outline only in the plan; rejected because the plan must not own scope. -- **Consequences:** `implementation-plan.md` may sequence documentation edits, - but must promote any newly discovered runtime/contract or architectural - decision to the appropriate owner before planning it. - -### DEC-53-02: Intake PRD stays outside Memory Bank until upstream adaptation - -- **Status:** accepted -- **Decision:** The protocol will require a temporary intake PRD outside - `memory-bank/` during pre-adaptation discovery, then govern/import it only - after the relevant baseline owners are adapted. -- **Question:** Where can discovery facts be safely recorded before Memory Bank - is allowed to influence discovery? -- **Evidence:** Issue #53 explicitly prescribes an evidence-backed intake PRD - outside `memory-bank/`, followed by conversion into `memory-bank/prd/` whose - `derived_from` links point only to already adapted upstream owners. It also - explicitly prohibits consulting `memory-bank/` during pre-adaptation - discovery. -- **FPF reasoning:** Treat pre-adaptation discovery and governed Memory Bank as - different bounded contexts. A temporary artifact can preserve evidence and - uncertainty without becoming an authority of the not-yet-installed governance - system. After owners exist, conversion creates the governed dependency graph; - collapsing the stages would let generic placeholders contaminate project - knowledge. -- **Consequences:** The protocol must specify a clearly named non-`memory-bank/` - location and preserve source references, confidence, conflicts and open - questions through conversion. - -### DEC-53-03: Default intake location is the repository root - -- **Status:** accepted -- **Decision:** The protocol's temporary intake PRD path is - `./brownfield-intake-prd.md`. -- **Question:** What exact location can the generic protocol prescribe without - assuming that a downstream repository already has a `docs/` directory or any - governed Memory Bank structure? -- **Evidence:** Issue #53 requires the protocol to define an intake PRD - location outside `memory-bank/`; pre-adaptation discovery occurs before - Memory Bank is consulted or installed. The issue does not establish any - repository-specific documentation directory. -- **FPF reasoning:** The pre-adaptation and governed contexts must remain - separate (`DEC-53-02`). The repository root is the only path boundary present - in every repository without importing an unproven convention; the selected - filename is explicit and cannot be mistaken for an artifact inside - `memory-bank/`. This supplies a deterministic hand-off while making no claim - about downstream documentation layout. -- **Alternatives considered:** `docs/brownfield-intake-prd.md` is rejected: a - `docs/` directory is not guaranteed by the evidence. An unspecified - non-`memory-bank/` path is rejected: it fails the issue's explicit location - requirement and weakens the hand-off. -- **Consequences:** The protocol will use this default path. A repository may - retain an existing local convention only when it records the chosen alternate - path and preserves all required intake fields and the outside-`memory-bank/` - boundary. diff --git a/memory-bank/features/FT-53/feature-review-report.md b/memory-bank/features/FT-53/feature-review-report.md deleted file mode 100644 index 990827f..0000000 --- a/memory-bank/features/FT-53/feature-review-report.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "FT-53: Feature Review Report" -doc_kind: feature -doc_function: reference -purpose: "Результат ограниченного review-improve комплекта FT-53; фиксирует findings, их disposition и verification evidence без переопределения canonical owners." -derived_from: - - brief.md - - decision-log.md - - implementation-plan.md -status: active -audience: humans_and_agents -must_not_define: - - ft_53_problem_space - - ft_53_selected_design - - ft_53_execution_sequence ---- - -# FT-53: Feature Review Report - -## Cycle 1 - -### Review summary - -Reviewed the complete package: `README.md`, canonical `brief.md`, -`decision-log.md` and `implementation-plan.md`, plus the explicit related -guidance in `docs/adoption.md` and `docs/greenfield-integration-protocol.md`. -The package has one canonical problem owner, no required design owner, an -execution plan derived from the brief, and complete `REQ -> SC/EC -> CHK -> -EVID` traceability. No contradiction between the decision log, brief and plan -was found. - -### Findings - -| ID | Priority | Finding | Disposition | -| --- | --- | --- | --- | -| `I-53-01` | important | Feature Flow requires the source issue to link back to `brief.md` and downstream feature documents; the package had only the forward issue link. | Closed: issue [#53 comment](https://github.com/dapi/memory-bank/issues/53#issuecomment-5046125234) links both `brief.md` and `implementation-plan.md`. | -| `I-53-02` | important | `implementation-plan.md` declares `EVID-53-09` at `feature-review-report.md`, but the referenced review artifact did not exist. | Closed by this document and its route from package `README.md`. | - -### Open questions closed through FPF - -- `DEC-53-01` in [`decision-log.md`](decision-log.md#dec-53-01-design-owner-not-required): no `design.md`. The issue limits the feature to documentation and navigation; no architecture, contract or runtime decision is needed. -- `DEC-53-02` in [`decision-log.md`](decision-log.md#dec-53-02-intake-prd-stays-outside-memory-bank-until-upstream-adaptation): keep the intake PRD outside `memory-bank/` until evidence-backed upstream owners exist. This follows the explicit staged lifecycle in issue #53 and prevents generic-template facts from entering discovery. - -### Changes made - -- Created and indexed this report. -- Added the tracker-to-feature links required by Feature Flow. - -### Human gate - -No. Issue #53 supplies unambiguous requirements for both decisions; no missing -fact materially changes FT-53 scope or acceptance. - -## Cycle 2 - -### Review summary - -Re-reviewed the package after cycle-1 corrections, including frontmatter, -`derived_from` links, package index reachability, canonical-owner boundaries, -decision/plan consistency and the verify chain. The Go CLI completed a full -Memory Bank audit successfully. - -### Findings - -| ID | Priority | Finding | Disposition | -| --- | --- | --- | --- | -| `I-53-03` | important | `REQ-53-03` required an exact temporary intake-PRD location, but the brief and plan only said «outside `memory-bank/`». | Closed by `DEC-53-03`: the generic default is `./brownfield-intake-prd.md`; the requirement and plan now reuse that canonical decision. | - -### Open questions closed through FPF - -- `DEC-53-03` in [`decision-log.md`](decision-log.md#dec-53-03-default-intake-location-is-the-repository-root): the repository root is the only evidence-independent path boundary; a `docs/` directory cannot be assumed before adaptation. The decision remains generic and preserves the mandatory outside-`memory-bank/` boundary. - -### Changes made - -- Added the exact intake location to `REQ-53-03`, decision record and plan precondition/step. -- Ran `go run ./cmd/memory-bank lint` from `tools/`: passed. - -### Human gate - -No. The location is a generic protocol convention whose selection follows the -issue's mandatory boundary and does not assert a downstream project fact. - -## Cycle 3 - -### Review summary - -Reviewed the final package for canonical-owner separation, decision-log/brief/ -plan agreement, frontmatter and `derived_from` integrity, package and root -index reachability, all `REQ -> SC/EC -> CHK -> EVID` paths, and references to -the related adoption and greenfield guidance. No `critical` or `important` -finding remains; the review-improve loop stops early after three cycles. - -### Findings - -None at `critical` or `important` priority. - -### Open questions closed through FPF - -None. All feature-material decisions are already recorded as `DEC-53-01` to -`DEC-53-03` in [`decision-log.md`](decision-log.md). - -### Changes made - -None; this was a convergence review. - -### Human gate - -No. - -## Verification status - -- `git diff --check`: passed during cycle 1. -- `go run ./cmd/memory-bank lint` from `tools/`: passed. The installed - `memory-bank` executable remains unavailable, but the same repository CLI - command completed the required lint audit successfully. -- `go test -count=1 -race ./...` from `tools/`: passed. -- `go vet ./...` from `tools/`: passed. -- `git diff --check`: passed. - -## Cycle 4: Delivery convergence - -### Review summary - -Reviewed the implemented change against `REQ-53-01`–`REQ-53-06` and issue #53. -`docs/brownfield-adaptation-protocol.md` owns the detailed lifecycle; root -navigation and `docs/adoption.md` route to it without retaining a contradictory -copy. The protocol preserves the pre-adaptation boundary, intake provenance, -conditional web-service/CLI coverage, safety rules, rollout DoD and copyable -prompt. No critical or important finding remains. - -### Evidence - -- `EVID-53-01`: semantic review of the protocol against the brief and issue. -- `EVID-53-02`: reconciliation read-through plus `git diff --check`. -- `EVID-53-03`: `go run ./cmd/memory-bank lint` and - `go run ./cmd/memory-bank doctor` from `tools/` both completed successfully. -- Supporting repository checks: `go test -count=1 -race ./...` and - `go vet ./...` from `tools/` completed successfully. - -### Human gate - -No. diff --git a/memory-bank/features/FT-53/implementation-plan.md b/memory-bank/features/FT-53/implementation-plan.md deleted file mode 100644 index 6acbb94..0000000 --- a/memory-bank/features/FT-53/implementation-plan.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: "FT-53: Implementation Plan" -doc_kind: feature -doc_function: derived -purpose: "Execution plan for the brownfield adaptation protocol without redefining FT-53 problem-space facts or validation profile." -derived_from: - - brief.md - - decision-log.md -status: archived -audience: humans_and_agents -must_not_define: - - ft_53_scope - - ft_53_selected_design - - ft_53_acceptance_criteria - - ft_53_blocker_state - - ft_53_validation_profile ---- - -# FT-53: Implementation Plan - -## Goal - -Deliver the documentation outcome defined by `REQ-53-01`–`REQ-53-06`, retaining -`brief.md` as the canonical owner of requirements and verification. - -## Grounding / Support References - -| Document | Role in this plan | Facts reused | Conflict action | -| --- | --- | --- | --- | -| [`brief.md`](brief.md) | Canonical problem, validation and verify owner | `REQ-53-*`, `SC-53-*`, `CHK-53-*`, `EVID-53-*` | Update brief first | -| [`decision-log.md`](decision-log.md) | Feature-local decision evidence | `DEC-53-01`, `DEC-53-02` | Update decision log and brief if problem-space facts change | -| [`../../../docs/adoption.md`](../../../docs/adoption.md) | Existing brownfield guidance to reconcile | Current inventory, order and readiness sections | Update canonical guidance rather than duplicate it | -| [`../../../docs/greenfield-integration-protocol.md`](../../../docs/greenfield-integration-protocol.md) | Adjacent lifecycle reference | Existing install/adaptation ordering | Escalate lifecycle conflict to brief before edits | - -`design.md`, support artifacts, contracts, diagrams and ADRs: `none`, per -`DEC-53-01` in [`brief.md`](brief.md#design-requirement-decision). - -## Current State / Reference Points - -| Path / module | Current role | Why relevant | Reuse / mirror | -| --- | --- | --- | --- | -| `docs/adoption.md` | Entry guidance for brownfield and greenfield adoption | Must link to the dedicated protocol and no longer carry contradictory lifecycle detail | Keep it as concise routing/summary guidance | -| `docs/greenfield-integration-protocol.md` | Executable neighboring protocol | Defines the expected level of lifecycle detail and source-evidence discipline | Mirror structure where applicable, not greenfield-specific facts | -| `README.md` | Root documentation navigation | Must make the new protocol discoverable | Add one annotated link | - -## Test Strategy - -Validation profile is `documentation`, selected only in [`brief.md`](brief.md#validation-profile-decision). - -| Test surface | Canonical refs | Planned coverage | Required local commands | Manual-only gap / justification | -| --- | --- | --- | --- | --- | -| Protocol completeness | `REQ-53-01`–`REQ-53-05`, `CHK-53-01` | Targeted semantic read-through | `git diff -- docs/adoption.md docs/brownfield-adaptation-protocol.md README.md` | Reviewer verifies prose meaning | -| Guidance reconciliation | `REQ-53-06`, `CHK-53-02` | Whitespace and lifecycle read-through | `git diff --check` | Reviewer compares lifecycle boundaries | -| Memory Bank navigation | `CHK-53-03` | Links and indexes | `memory-bank lint` | If unavailable, state exact gap and use brief fallback | - -## Open Questions / Ambiguities - -none. `DEC-53-01` and `DEC-53-02` are closed from issue evidence in -[`decision-log.md`](decision-log.md); no open question blocks planning. - -## Environment Contract - -| Area | Contract | Used by | Failure symptom | -| --- | --- | --- | --- | -| setup | Run from repository root with Git available | `STEP-53-01`–`STEP-53-04` | Paths or diff evidence cannot be resolved | -| test | `memory-bank lint` is the primary navigation check; `git diff --check` checks whitespace | `CHK-53-02`, `CHK-53-03` | Missing command produces a stated verification gap, not a pass | -| access / network / secrets | No secrets, external access or runtime environment is required | all steps | Any request to copy sensitive project data stops the work and triggers scope escalation | - -## Preconditions - -| Precondition ID | Canonical ref | Required state | Used by steps | Blocks start | -| --- | --- | --- | --- | --- | -| `PRE-53-01` | `DEC-53-01` | Feature remains documentation-only | `STEP-53-01`–`STEP-53-04` | yes | -| `PRE-53-02` | `DEC-53-02`, `DEC-53-03` | Intake PRD lifecycle remains evidence-backed, staged and starts at `./brownfield-intake-prd.md` | `STEP-53-01` | yes | - -## Design Realization Mapping - -Not applicable: `Design required: no` in [`brief.md`](brief.md#design-requirement-decision). - -## Workstreams - -| Workstream | Implements | Result | Owner | Dependencies | -| --- | --- | --- | --- | --- | -| `WS-53-01` | `REQ-53-01`–`REQ-53-05` | Dedicated generic brownfield protocol | agent | `PRE-53-01`, `PRE-53-02` | -| `WS-53-02` | `REQ-53-06` | Reconciled adoption/root navigation | agent | `WS-53-01` | -| `WS-53-03` | `CHK-53-01`–`CHK-53-03` | Verification evidence or explicit gap | agent / reviewer | `WS-53-01`, `WS-53-02` | - -## Approval Gates - -None. The `documentation` validation profile requires ordinary review only; -any scope expansion to runtime, secrets or project-specific facts must stop and -be escalated under `STOP-53-01`. - -## Work Sequence - -| Step ID | Actor | Implements | Goal | Touchpoints | Artifact | Verifies | Evidence IDs | Check command / procedure | Blocked by | Needs approval | Escalate if | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| `STEP-53-01` | agent | `REQ-53-01`–`REQ-53-05` | Write protocol with staged discovery, intake at `./brownfield-intake-prd.md`, adaptation, conversion, conditional inventory, safety and DoD | `docs/brownfield-adaptation-protocol.md` | New protocol | `CHK-53-01` | `EVID-53-01` | Compare every section with brief and issue | `PRE-53-01`, `PRE-53-02` | none | An unresolvable conflict with canonical guidance appears | -| `STEP-53-02` | agent | `REQ-53-06` | Replace detailed brownfield lifecycle in adoption docs with concise route; link root navigation | `docs/adoption.md`, `README.md` | Reachable guidance | `CHK-53-02` | `EVID-53-02` | Read all three lifecycle documents together | `STEP-53-01` | none | A required change affects unrelated guidance | -| `STEP-53-03` | agent | `CHK-53-01`, `CHK-53-02` | Run documentation integrity checks | changed docs | Review result | `CHK-53-01`, `CHK-53-02` | `EVID-53-01`, `EVID-53-02` | `git diff --check`; semantic read-through | `STEP-53-02` | none | A requirement cannot be evidenced from issue or docs | -| `STEP-53-04` | agent | `CHK-53-03` | Verify Memory Bank links/indexes and record result | `memory-bank/` | Lint result or gap | `CHK-53-03` | `EVID-53-03` | `memory-bank lint`, otherwise fallback in brief | `STEP-53-02` | none | Lint reports unresolved issue outside feature scope | - -## Checkpoints - -| Checkpoint ID | Refs | Condition | Evidence IDs | -| --- | --- | --- | --- | -| `CP-53-01` | `STEP-53-01`, `CHK-53-01` | All required protocol sections trace to `REQ-53-*` IDs | `EVID-53-01` | -| `CP-53-02` | `STEP-53-02`, `CHK-53-02` | Adoption, root and greenfield paths have compatible lifecycle boundaries | `EVID-53-02` | -| `CP-53-03` | `STEP-53-04`, `CHK-53-03` | Lint passes or exact verification gap is captured | `EVID-53-03` | - -## Execution Risks - -| Risk ID | Risk | Impact | Mitigation | Trigger | -| --- | --- | --- | --- | --- | -| `ER-53-01` | Protocol duplicates and drifts from adoption guidance | Conflicting instructions | Keep adoption as short routing and protocol as detailed lifecycle owner | Same lifecycle rule has different wording/order | -| `ER-53-02` | Generic guidance asserts downstream facts | Unsafe adaptation | Require source references, confidence and explicit unknown/conflict records | Draft names an unsupported product, endpoint, secret or owner | - -## Stop Conditions / Fallback - -| Stop ID | Related refs | Trigger | Immediate action | Safe fallback state | -| --- | --- | --- | --- | --- | -| `STOP-53-01` | `CON-53-01`, `NS-53-01`, `NS-53-02` | Edit needs project-specific facts, secrets, runtime behavior or unproven lifecycle choice | Stop and request human decision with evidence/options | Keep scoped documentation draft; do not claim completion | - -## Plan-local Evidence - -| Evidence ID | Artifact | Producer | Path contract | Reused by checkpoints | -| --- | --- | --- | --- | --- | -| `EVID-53-09` | Feature-pack review report | documentation quality agent | `memory-bank/features/FT-53/feature-review-report.md` | final handoff | - -## Ready for Acceptance - -- All workstreams and checkpoints are complete. -- `CHK-53-01`–`CHK-53-03` have evidence or the permitted verification gap is explicit. -- Final acceptance follows [`brief.md`](brief.md#verify), not this plan. diff --git a/memory-bank/features/README.md b/memory-bank/features/README.md index 6d837b5..b1aee59 100644 --- a/memory-bank/features/README.md +++ b/memory-bank/features/README.md @@ -26,12 +26,6 @@ audience: humans_and_agents - Если feature реализует или существенно меняет устойчивый сценарий проекта, она должна ссылаться на соответствующий `UC-*` из [`../use-cases/README.md`](../use-cases/README.md). - В шаблонном репозитории этот каталог может быть пустым. Это нормально. -## Packages - -- [`FT-53/`](FT-53/) - Protocol безопасной адаптации Memory Bank в существующем (brownfield) - репозитории. - ## Naming - Базовый формат: `FT-XXX/` From 5bcbacebfcef10607b3ffc218dd809ce6b7efebb Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Thu, 23 Jul 2026 18:17:22 +0300 Subject: [PATCH 5/5] docs: use external CLI in brownfield protocol --- docs/brownfield-adaptation-protocol.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/brownfield-adaptation-protocol.md b/docs/brownfield-adaptation-protocol.md index 5257dc5..4fe2adf 100644 --- a/docs/brownfield-adaptation-protocol.md +++ b/docs/brownfield-adaptation-protocol.md @@ -117,11 +117,11 @@ historical ADR — только для уже принятых и всё ещё ### 7. Validate и trial -Обновите README indexes и `derived_from` links. Запустите `memory-bank lint` и -`memory-bank doctor`; если команда недоступна, запишите точную verification gap -и выполните доступную проверку ссылок/структуры. Затем используйте adapted -context в одной реальной task через подходящий flow до объявления rollout -complete. +Обновите README indexes и `derived_from` links. Запустите +`memory-bank-cli lint` и `memory-bank-cli doctor`; если команда недоступна, +запишите точную verification gap и выполните доступную проверку +ссылок/структуры. Затем используйте adapted context в одной реальной task через +подходящий flow до объявления rollout complete. ## Product-type considerations @@ -170,8 +170,8 @@ Inventory и owner-документы conditional: не создавайте irr если он известен. - [ ] Use cases и historical ADRs созданы только при source evidence; лишние delivery artifacts не созданы. -- [ ] `memory-bank lint` и `memory-bank doctor` успешны либо verification gap - указан без заявления об успехе. +- [ ] `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. @@ -186,5 +186,6 @@ CI/CD, configuration, runbooks и historical ADR. Запиши evidence-backed i 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 и проверь lint/doctor. +из того же evidence, конвертируй intake в governed PRD и проверь +memory-bank-cli lint/doctor. ```