chore(memory): align ADR guidance with PR-link format #71

New issue

Closed

opened 2026-08-16 17:28:21 +03:00 by slaid098 · 0 comments

slaid098 commented

2026-08-16 17:28:21 +03:00

Owner

Контекст

ADR-файлы в docs/decisions/ больше не создаются (практика закрыта, репо оставляет старые файлы как архив; см. PR#208/209/210). Живой формат указателя на архитектурное решение: [date, PR#N] <суть решения> со ссылкой на pull request как источник истины — memory-syncer.md уже содержит этот урезанный формат (строка ~60), но memory/SKILL.md до сих пор документирует старый формат (ADR-NN: ... → docs/decisions/NN-title.md + «Не копируй содержание ADR»). В глобальной памяти (~/.local/share/opencode/opencode-memory/) остались инструкции-раритеты: раздел «ADR Index» с конвенцией sequential-нумерации в repos/slaid098/opencode-config.md, инструкция про удалённый сканер ADR-refs, упоминания ADR_DIR в тестовом скаффолдинге, устаревший workflow-план.

Зачем: инструкции для модели не должны расходиться с практикой — конфликтующие форматы порождают мусорные записи в памяти. Решение при планировании: ADR-указатели ОСТАЮТСЯ, но только как PR-ссылки; исторические ссылки ADR-NNN и файлы docs/decisions НЕ редактируются.

Задача

.opencode/skills/memory/SKILL.md — переписать секцию ### ADR — только указатель (строки ~97-103): новый формат записи - [YYYY-MM-DD, PR#N] <суть решения> + пояснение, что источник истины — PR#N (обсуждение и body), ссылки на docs/decisions/ больше НЕ пишутся, нумерация ADR-NN отменена. Убрать фразу «Не копируй содержание ADR — только указатель на файл».
.opencode/agents/memory-syncer.md (строка ~60) — привести пункт про ADR pointers к тому же PR-link формату, убрать рудиментарное «исторические».
Глобальная память (правки через Write/Edit + memory-save):
- repos/slaid098/opencode-config.md — раздел «## ADR Index (sequential per repo, NOT PR number)» пометить как исторический (новые записи не добавляются), убрать конвенцию нумерации «sequential max+1»; сам индекс старых записей оставить.
- technical/regex-scanner-blocks-own-documentation.md — инструкция про ADR-regex-сканер устарела (сканер удалён в PR#210): пометить stale в первой строке или переписать инструкцию на общий gotcha без привязки к сканеру.
- technical/pipeline-status-test-scaffold.md — упоминание ADR_DIR monkeypatch частично stale (check_adr удалён в PR#208): пометить.
- workflows/code-factory-event-driven-plan.md — пометить устаревшим (упоминает удалённый docs-reviewer и создание ADR).
НЕ редактировать исторические ссылки ADR-NNN в комментариях кода/скиллах (check-permissions.py reasons, reviewer.md, spec/SKILL.md, configure-opencode/SKILL.md, run-pipeline/SKILL.md, tools/_shared.ts и т.п.).
docs/decisions/ — не трогать вообще.

Контракты

Единый формат ADR-указателя во всех инструкциях: - [YYYY-MM-DD, PR#N] <суть решения> (без ADR-NN, без → docs/decisions).
Изменение памяти коммитится через memory-save (стандартный flow).

Инварианты

Исторические файлы/ссылки не трогаем — правим только инструкции-практики.
Правки конфига только в workspace clone /root/workspace/opencode-config/.
Формат обычных durable-записей памяти не меняется.

Граничные случаи

Директория памяти отсутствует/пустая в окружении исполнителя — тогда выполнить только пункты 1-2 (репо) и зафиксировать gap в PR body ## Pending.
Если в памяти найдутся дополнительные файлы с практикой ADR-нумерации (grep ADR по инструкциям) — обработать по тому же принципу и перечислить в PR body.

Влияние на связанные компоненты

memory-syncer — его инструкции меняются (п.2): проверить, что MEMORY-фаза pipeline остаётся работоспособной (квитанции PR#N не меняются).
issues и PR-шаблоны — без изменений.
Оркестратор/прочие агенты читают память через memory-search — новый формат читаем stripos/regex-agnostic, валидации формата в коде нет.

Вне scope

Содержимое docs/decisions/ и его удаление/архивация.
Удаление исторических ADR-NNN записей из памяти.
Serena (отдельный issue).

Критерии приемки

rg "docs/decisions" .opencode/skills/memory/ .opencode/agents/memory-syncer.md — только формулировки «historical/архив», ни одной живой инструкции со ссылкой на файл.
rg "ADR-NN" по тем же путям — ни одного совпадения как практики.
В памяти (~/.local/share/opencode/opencode-memory/) нет инструкции «sequential per repo» нумерации.
pytest tests/ репо зелёные; CI зелёный.
memory-save выполнен (если память доступна) либо gap зафиксирован в ## Pending.

## Контекст ADR-файлы в `docs/decisions/` больше не создаются (практика закрыта, репо оставляет старые файлы как архив; см. PR#208/209/210). Живой формат указателя на архитектурное решение: `[date, PR#N] <суть решения>` со ссылкой на pull request как источник истины — memory-syncer.md уже содержит этот урезанный формат (строка ~60), но `memory/SKILL.md` до сих пор документирует старый формат (`ADR-NN: ... → docs/decisions/NN-title.md` + «Не копируй содержание ADR»). В глобальной памяти (`~/.local/share/opencode/opencode-memory/`) остались инструкции-раритеты: раздел «ADR Index» с конвенцией sequential-нумерации в `repos/slaid098/opencode-config.md`, инструкция про удалённый сканер ADR-refs, упоминания `ADR_DIR` в тестовом скаффолдинге, устаревший workflow-план. Зачем: инструкции для модели не должны расходиться с практикой — конфликтующие форматы порождают мусорные записи в памяти. Решение при планировании: ADR-указатели ОСТАЮТСЯ, но только как PR-ссылки; исторические ссылки ADR-NNN и файлы docs/decisions НЕ редактируются. ## Задача 1. `.opencode/skills/memory/SKILL.md` — переписать секцию `### ADR — только указатель` (строки ~97-103): новый формат записи `- [YYYY-MM-DD, PR#N] <суть решения>` + пояснение, что источник истины — PR#N (обсуждение и body), ссылки на `docs/decisions/` больше НЕ пишутся, нумерация ADR-NN отменена. Убрать фразу «Не копируй содержание ADR — только указатель на файл». 2. `.opencode/agents/memory-syncer.md` (строка ~60) — привести пункт про ADR pointers к тому же PR-link формату, убрать рудиментарное «исторические». 3. Глобальная память (правки через Write/Edit + memory-save): - `repos/slaid098/opencode-config.md` — раздел «## ADR Index (sequential per repo, NOT PR number)» пометить как исторический (новые записи не добавляются), убрать конвенцию нумерации «sequential max+1»; сам индекс старых записей оставить. - `technical/regex-scanner-blocks-own-documentation.md` — инструкция про ADR-regex-сканер устарела (сканер удалён в PR#210): пометить stale в первой строке или переписать инструкцию на общий gotcha без привязки к сканеру. - `technical/pipeline-status-test-scaffold.md` — упоминание `ADR_DIR` monkeypatch частично stale (check_adr удалён в PR#208): пометить. - `workflows/code-factory-event-driven-plan.md` — пометить устаревшим (упоминает удалённый docs-reviewer и создание ADR). 4. НЕ редактировать исторические ссылки ADR-NNN в комментариях кода/скиллах (check-permissions.py reasons, reviewer.md, spec/SKILL.md, configure-opencode/SKILL.md, run-pipeline/SKILL.md, tools/_shared.ts и т.п.). 5. `docs/decisions/` — не трогать вообще. ## Контракты - Единый формат ADR-указателя во всех инструкциях: `- [YYYY-MM-DD, PR#N] <суть решения>` (без ADR-NN, без → docs/decisions). - Изменение памяти коммитится через `memory-save` (стандартный flow). ## Инварианты - Исторические файлы/ссылки не трогаем — правим только инструкции-практики. - Правки конфига только в workspace clone `/root/workspace/opencode-config/`. - Формат обычных durable-записей памяти не меняется. ## Граничные случаи - Директория памяти отсутствует/пустая в окружении исполнителя — тогда выполнить только пункты 1-2 (репо) и зафиксировать gap в PR body ## Pending. - Если в памяти найдутся дополнительные файлы с практикой ADR-нумерации (grep `ADR` по инструкциям) — обработать по тому же принципу и перечислить в PR body. ## Влияние на связанные компоненты - memory-syncer — его инструкции меняются (п.2): проверить, что MEMORY-фаза pipeline остаётся работоспособной (квитанции `PR#N` не меняются). - `issues` и PR-шаблоны — без изменений. - Оркестратор/прочие агенты читают память через memory-search — новый формат читаем stripos/regex-agnostic, валидации формата в коде нет. ## Вне scope - Содержимое `docs/decisions/` и его удаление/архивация. - Удаление исторических ADR-NNN записей из памяти. - Serena (отдельный issue). ## Критерии приемки - [ ] `rg "docs/decisions" .opencode/skills/memory/ .opencode/agents/memory-syncer.md` — только формулировки «historical/архив», ни одной живой инструкции со ссылкой на файл. - [ ] `rg "ADR-NN"` по тем же путям — ни одного совпадения как практики. - [ ] В памяти (`~/.local/share/opencode/opencode-memory/`) нет инструкции «sequential per repo» нумерации. - [ ] `pytest tests/` репо зелёные; CI зелёный. - [ ] memory-save выполнен (если память доступна) либо gap зафиксирован в ## Pending.

slaid098 added the

chore

label

2026-08-16 17:28:21 +03:00

slaid098 referenced this issue from a pull request that will close it,

2026-08-16 18:12:16 +03:00

chore(memory): align ADR guidance with PR-link format #79

slaid098 closed this issue

2026-08-16 18:13:48 +03:00