Skip to content

refactor: make project-local memory bank a projection of the payload - #134

Merged
dapi merged 1 commit into
mainfrom
refactor/memory-bank-as-projection
Sep 6, 2026
Merged

refactor: make project-local memory bank a projection of the payload#134
dapi merged 1 commit into
mainfrom
refactor/memory-bank-as-projection

Conversation

@dapi

@dapi dapi commented Sep 5, 2026

Copy link
Copy Markdown
Owner

Суть

memory-bank/ перестаёт быть копией payload и становится его проекцией: generic-документы — симлинки в template/memory-bank/. Инстанс равен payload по построению, синхронизировать нечего.

Почему копия была неверной моделью

Репозиторий — источник шаблона, а не downstream-установка. CLI сообщает это прямо, стоит убрать лок:

$ memory-bank-cli doctor --profile template
info  template.source_repository  Template source profile detected;
      an installed-template lock is not expected.
      remediation: Create locks only in downstream repositories through memory-bank-cli init.
Result: 0 error(s), 0 warning(s), 1 info

Пока лок был на месте, тот же doctor выдавал 110 ошибок manifest.managed_unreadable — по одной на каждый проецируемый документ. Лок описывал дрейф от внешнего шаблона, которого у источника нет.

Из этой же неверной модели выросла вчерашняя машинерия: pull в изолированной песочнице, ручная миграция лока и запрос на subtree-scope в апстрим (dapi/memory-bank-cli#60). Всё это обслуживало дублирование, которого не должно было быть.

Что изменилось

Было Стало
Generic-документы 110 копий 110 симлинков в payload
Свои документы 26 файлов те же 26 файлов
memory-bank/.lock 119 записей удалён
Синхронизация sync-project-memory-bank.rb: песочница + pull + перенос + правка лока refresh-memory-bank-projection.rb: досоздать симлинки

Правило переопределения стало явным: заменил симлинк обычным файлом — документ project-specific, и git показывает смену типа; удалил файл и прогнал скрипт — вернулся в проекцию.

Почему пофайлово, а не покаталожно

Пробовал memory-bank/flows -> ../template/memory-bank/flows. lint не спускается в симлинк на директорию: область упала со 120 файлов до 68, и все ссылки в flows/ объявлены битыми. Ограничение зафиксировано в docs/memory-bank.md, чтобы следующий не наступил на те же грабли.

Защита от рассинхронизации

Забыть симлинк для нового документа payload нельзя: индекс инстанса ссылается на него, и memory-bank-cli lint --repo-root . падает с битой ссылкой. То есть CI ловит пропуск, а не человек.

Проверки

  • lint --repo-root . — OK, 120 файлов в области (было 110), ни одной битой ссылки;
  • lint --scope-root template/memory-bank — OK;
  • doctor --profile template — 0 ошибок;
  • валидатор priming-манифестов и его тест — OK;
  • smoke-тест установки в чистый репозиторий — downstream по-прежнему получает настоящую копию с локом: поведение продукта не затронуто, изменилась только модель догфудинга.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RtxeRwhVf1y8zvxUtk6xrS

`memory-bank/` был полной копией payload: 110 файлов дублировали
`template/memory-bank/`, а расхождение отслеживалось локом. Отсюда росла вся
вчерашняя машинерия синхронизации — pull в песочнице, ручная миграция лока и
запрос на subtree-scope в апстрим.

Копия была неверной моделью. Этот репозиторий — источник шаблона, а не его
downstream-установка, и CLI говорит это прямо: после удаления лока
`doctor --profile template` сообщает «Template source profile detected; an
installed-template lock is not expected. Create locks only in downstream
repositories through memory-bank-cli init» и завершается без ошибок.

Теперь generic-документы — симлинки в payload, поэтому инстанс равен payload по
построению и синхронизировать нечего. Реальными файлами остались только 26
документов, которыми владеет или которые переопределяет проект: `features/`,
`research/`, `adr/`, project-specific части `product/` и `ops/`, индекс и
`bootstrap.md`.

- удалён `memory-bank/.lock`;
- `tools/sync-project-memory-bank.rb` заменён на
  `tools/refresh-memory-bank-projection.rb`: он лишь досоздаёт симлинки, чинит
  цели и убирает указывающие на исчезнувший payload, не трогая реальные файлы;
- переопределение теперь делается заменой симлинка обычным файлом и видно в git
  как смена типа;
- пропущенный симлинк ловится `lint --repo-root .` как битая ссылка, поэтому
  проекция не может молча отстать.

Проекция пофайловая: `lint` не спускается в симлинк на директорию и объявляет
её содержимое недостижимым, поэтому симлинк на каталог не подходит.

Поведение продукта не затронуто: downstream по-прежнему получает настоящую копию
с локом, что подтверждает smoke-тест установки в чистый репозиторий.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RtxeRwhVf1y8zvxUtk6xrS
@dapi
dapi merged commit 0562798 into main Sep 6, 2026
1 check passed
dapi added a commit that referenced this pull request Sep 6, 2026
…bsystem

* origin/main:
  docs: make the review mechanism an explicit, verifiable choice (#139)
  docs: add WAIT status for external events without a human gate (#138)
  docs: bound review convergence across delivery flows (#137)
  chore: pin memory-bank-cli v2.3.0 in CI (#136)
  refactor: make project-local memory bank a projection of the payload (#134)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant