| 1 | # ADR 017: Knowledge-roots registry — префиксы (не каталог всех файлов group) |
| 2 | |
| 3 | **Статус:** Accepted · **2026-05-19** · Core **2.1.2** |
| 4 | **Реализация (код):** репозиторий **AIGuiders.AgentNotes.Core** / `agent-notes-core` — `docs/adr/016-knowledge-roots-registry-prefix-v1.md` (полный текст) |
| 5 | **Расширяет:** [013](013-agent-notes-mcp-local-settings-toml-v1.md); agent-notes-mcp ADR 015 (`docs/adr/015-multi-root-read-only-knowledge-routing-v1.md`) |
| 6 | **Связано:** [011](011-aiguiders-org-collaborative-kb-repo-v1.md), `work/org/scope-contour-map-v1.md`, [008](008-workspace-scope-map-hot-mcp-and-public-cut.md) |
| 7 | |
| 8 | --- |
| 9 | |
| 10 | ## Суть (одним абзацем) |
| 11 | |
| 12 | **Читать** из group KB можно **любой** файл — TOML уже монтирует весь clone. Файл `work/local/knowledge-roots-index-v1.md` нужен **не для доступа**, а чтобы `route_context` подсказал агенту: «это в group, вот preview». Перечислять каждую карточку `work/projects/.../README.md` **не надо**. Вместо этого — **2–5 строк**: smoke, префикс `work/org/`, префикс `work/projects/<group-scope-dir>/`. Имена scope-каталогов — в **`work/org/scope-contour-map-v1.md`**, не в roots-index. |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## Три механизма (не путать) |
| 17 | |
| 18 | ```text |
| 19 | TOML [[knowledge.read_only]] id=group |
| 20 | → read_knowledge_file(любой/путь, knowledge_root_id=group) |
| 21 | |
| 22 | work/org/scope-contour-map-v1.md |
| 23 | → таблица: personal scope slug ↔ group catalog dir |
| 24 | |
| 25 | work/local/knowledge-roots-index-v1.md |
| 26 | → якоря для route_context (exact file или prefix/) |
| 27 | ``` |
| 28 | |
| 29 | --- |
| 30 | |
| 31 | ## Формат индекса (после внедрения Core 2.1.2) |
| 32 | |
| 33 | ```text |
| 34 | group/smoke-test-v1.md => group |
| 35 | work/org/ => group |
| 36 | work/projects/aiguiders-open/ => group |
| 37 | ``` |
| 38 | |
| 39 | - Строка **без** `/` в конце пути — один файл. |
| 40 | - Строка **с** `/` в конце — весь подкаталог (префикс). |
| 41 | - Комментарии `#` — для человека; соглашения дублируются в hot `knowledge-roots-routing-v1`. |
| 42 | |
| 43 | Полная спецификация и план кода — **ADR 016** в репозитории AgentNotes.Core (ссылка выше). |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## Что меняется в KB (после accept) |
| 48 | |
| 49 | | Артефакт | Изменение | |
| 50 | |----------|-----------| |
| 51 | | `work/local/README.md` | «реестр = подсказки route_context», не whitelist | |
| 52 | | `templates/newcomer/template-clean-setup-knowledge-roots-index-v1.md` | примеры с `/` | |
| 53 | | `agent-notes.md` § `knowledge-roots-routing-v1` | одна строка: open stack в group → `work/projects/<group-scope-dir>/` | |
| 54 | | Личный `knowledge-roots-index-v1.md` | убрать per-file `work/org/scope-contour...`; оставить префиксы | |
| 55 | |
| 56 | --- |
| 57 | |
| 58 | ## Не в scope |
| 59 | |
| 60 | - Авто-подстановка `knowledge_root_id` в тулах без явного параметра. |
| 61 | - Замена scope-contour-map префиксами в roots-index. |
| 62 | |
| 63 | |