| 1 | # ADR 011: GitHub-организация AI-Guiders и репозиторий совместной KB (`AI-Guiders/kb`) |
| 2 | |
| 3 | > **Для любой другой org:** нормативный white-label onboarding — [`../domains/agent-operations/playbook-org-kb-white-label-v1.md`](../domains/agent-operations/playbook-org-kb-white-label-v1.md) (плейсхолдер `{ORG_SLUG}`). Этот ADR — **решение и история инстанса AI-Guiders**, не универсальная инструкция. |
| 4 | |
| 5 | **Статус:** Accepted (2026-06-12) |
| 6 | **Дата:** 2026-05-15 |
| 7 | **Именование GitHub:** org slug — **`AI-Guiders`** (с дефисом). Репозитории: `AI-Guiders/kb`, `AI-Guiders/kb-public`. Бренд/NuGet «AIGuiders» (без дефиса) — не путать с org slug. |
| 8 | **Источник в истории:** перенос open-репозиториев в GitHub-организацию [AI-Guiders](https://github.com/AI-Guiders); запрос на отдельный **живой** контур KB для коллаборации (общие линии, совместное пополнение), не только read-only зеркало `kb-public`. |
| 9 | **Supersedes:** — |
| 10 | **Extended by:** — |
| 11 | **Связано:** [001](001-kb-public-publishing-pipeline.md), [007](007-kb-project-constitution.md), [008](008-workspace-scope-map-hot-mcp-and-public-cut.md), [003](003-multi-project-scope-and-project-cards.md), [012](012-multi-canon-workspace-resolution-v1.md) |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## Терминология (зафиксировать в обсуждениях) |
| 16 | |
| 17 | | Термин | Где | Смысл | |
| 18 | |--------|-----|--------| |
| 19 | | **Личный канон** (chmod **u**) | `agent-notes` | SSOT владельца: `work/local/`, `personal/`, hot, полный `work/projects/`. | |
| 20 | | **Group KB** (chmod **g**) | репо **`AI-Guiders/kb`**, MCP `knowledge_root_id=group` | **SSOT общего знания:** пары (человек+агент) пишут PR/export; все читают. | |
| 21 | | **Org KB** | то же репо `AI-Guiders/kb` | Синоним в текстах про **GitHub org**, governance, `seed-org-kb.ps1`, **org-maintainer**. Не меняет MCP id (`group`). | |
| 22 | | **Public KB** (chmod **o**) | `AI-Guiders/kb-public` | Публичный срез; `public-kb.ignore`. | |
| 23 | | **Open-код** | `AI-Guiders/*` | MCP, IDE, Core — не текст KB. | |
| 24 | |
| 25 | **Правило:** в ADR/MCP/ugo пишем **group KB**; **org KB** — только про репозиторий на GitHub и роли maintainers. Файл исключений seed: `knowledge/group-kb.ignore`. |
| 26 | |
| 27 | Далее в ADR: **личный канон** вместо устаревшего «полный канон». |
| 28 | |
| 29 | --- |
| 30 | |
| 31 | ## Контекст |
| 32 | |
| 33 | Сейчас в экосистеме фактически **три роли** контента знаний (+ код), но названия путаются — см. таблицу выше. |
| 34 | |
| 35 | Появление **организации AI-Guiders** на GitHub поднимает вопрос: нужен ли **организационный** контур — репозиторий, куда **участники org** вносят общие линии (playbook/kb/worlds), с PR и review, **без** доступа к **личному канону** и **без** утечки машинных путей и слоя `knowledge/personal/`. |
| 36 | |
| 37 | Ограничения, которые уже закреплены и не отменяем этим ADR: |
| 38 | |
| 39 | - [001](001-kb-public-publishing-pipeline.md) — публичная сборка режется по `public-cut` и `public-kb.ignore`. |
| 40 | - [007](007-kb-project-constitution.md) — Privacy by Architecture, Router-First, SSOT в каноне. |
| 41 | - [008](008-workspace-scope-map-hot-mcp-and-public-cut.md) — карты workspace и операционный спринт **не** в kb-public hot. |
| 42 | |
| 43 | Проблема без отдельного org-репо: либо коллаборанты пушат в **личный** `agent-notes` (нежелательно), либо работают только с **мертвым** zip/`kb-public` без нормального git-flow, либо дублируют знания в разрозненных README репозиториев кода. |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## Цели (что хотим получить) |
| 48 | |
| 49 | 1. **Совместное пополнение** — общие playbook/kb, маршруты, worlds/domains, META (Integrity POST), онбординг — через PR в GitHub org. |
| 50 | 2. **Общие линии** — согласованные формулировки принципов, протоколов `[HUMAN]`/`[WORK]`/`[PRIMARY]`, entry-структура ([009](009-kb-entry-structure-and-pre-open-onboarding.md)) без привязки к диску `C:\…`. |
| 51 | 3. **Предсказуемый MCP** — у участника `AGENT_NOTES_CANON_PATH` (или fork) указывает на **клон org-kb**; `read_hot_context` / `read_knowledge_file` работают как с kb-public (manifest + контрактный hot). |
| 52 | 4. **Разделение с личным каноном** — `work/local/`, `personal/`, карты workspace, hot ниже `public-cut` остаются **вне** org-kb; **`work/projects/`** — в org (обезличенные карточки). |
| 53 | 5. **Предпосылка участника** — перед работой в мульти-scope workspace: свой `work/local/workspace-scope-map-v1.md` в **личном** каноне ([008](008-workspace-scope-map-hot-mcp-and-public-cut.md), [012](012-multi-canon-workspace-resolution-v1.md)). |
| 54 | 6. **Совместимость** с существующим `kb-public` (не ломать потребителей read-only зеркала, пока не решим иное). |
| 55 | |
| 56 | --- |
| 57 | |
| 58 | ## Не-цели (явно не в scope ADR) |
| 59 | |
| 60 | - Перенос **личного канона** (`agent-notes` целиком) в org — личное и машинное остаётся у держателя канона. |
| 61 | - Замена NuGet / MCP-репозиториев этим репо (код по-прежнему в отдельных репо). |
| 62 | - Автоматический двусторонний sync «любой PR в org-kb → сразу в личный канон» без review держателя канона. |
| 63 | |
| 64 | --- |
| 65 | |
| 66 | ## Варианты |
| 67 | |
| 68 | ### A. Только переименовать/перенести `kb-public` → `AI-Guiders/kb` |
| 69 | |
| 70 | - Org-репо = тот же артефакт, что `build-public-kb.ps1`, пушится CI или скриптом с машины владельца. |
| 71 | - **Плюсы:** минимум новой механики; один источник правды для публичного среза. |
| 72 | - **Минусы:** коллаборанты **не пишут** в живой git напрямую (только PR в agent-notes у владельца → пересборка); org-kb остаётся зеркалом, не «местом работы». |
| 73 | |
| 74 | ### B. `AI-Guiders/kb` — **живой** collaborative repo (**принято**) |
| 75 | |
| 76 | - Участники org (пары A/B/C по доменам) коммитят/мержат PR **в `AI-Guiders/kb`** в согласованных зонах (`knowledge/worlds/`, `knowledge/domains/`, router, META, шаблоны). |
| 77 | - **Routine sync из одного канона не затирает org:** steady state — PR или `export-to-org-kb.ps1`. Full replace — только `bootstrap-org-kb.ps1` или `seed-org-kb.ps1 -Push` (bootstrap/DR). |
| 78 | - Держатель **личного канона** **импортирует** из org (`import-from-org-kb.ps1`) когда хочет писать локально; **экспортирует** только свои paths — не весь `knowledge/`. |
| 79 | - **Плюсы:** настоящая коллаборация; понятный CONTRIBUTING; MCP на клон org. |
| 80 | - **Минусы:** риск **двух SSOT** без дисциплины; нужны CODEOWNERS, шаблон PR, возможно `knowledge/collab/` vs зоны только maintainer’ов. |
| 81 | |
| 82 | ### C. Org-kb как **upstream** для `kb-public` |
| 83 | |
| 84 | - `AI-Guiders/kb` — живой; `KarataevDmitry/kb-public` (или release) — периодический **тегированный снимок** / GitHub Release zip для внешних без доступа к org. |
| 85 | - **Плюсы:** внешний мир не зависит от членства в org. |
| 86 | - **Минусы:** два шага публикации, если оба нужны. |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Предлагаемое решение (принято) |
| 91 | |
| 92 | Принят **вариант B** (federation) с опциональным **C** для внешних зеркал: |
| 93 | |
| 94 | ### 0. Federation (пары и домены) |
| 95 | |
| 96 | - **Org-first для shared:** общее знание развивается в `AI-Guiders/kb`; пары специализируются (Security, Psychology, open stack, …). |
| 97 | - **Read:** любой участник — clone org, MCP `knowledge_root_id=group`. |
| 98 | - **Write в org:** PR или `export-to-org-kb.ps1` (whitelist `knowledge/work/local/group-kb.export`, опционально). |
| 99 | - **Write в канон:** opt-in — `import-from-org-kb.ps1`, локальные правки, при необходимости export своей зоны обратно. |
| 100 | - **Запрещено в steady state:** full replace `knowledge/` из одного канона; bootstrap — `bootstrap-org-kb.ps1` / `seed-org-kb.ps1 -Push` (редко). |
| 101 | |
| 102 | Runbook: [`../work/projects/door-to-singularity/agent-notes-kb/templates/runbook-org-kb-federation-v1.md`](../work/projects/door-to-singularity/agent-notes-kb/templates/runbook-org-kb-federation-v1.md). |
| 103 | |
| 104 | ### 1. Репозиторий |
| 105 | |
| 106 | - **Имя:** `AI-Guiders/kb` (или `AI-Guiders/knowledge-base` — зафиксировать одно; ниже — `kb`). |
| 107 | - **Видимость:** private или public внутри org — **решение отдельно** (см. «Открытые вопросы»). |
| 108 | - **Лицензия:** выровнять с публичным срезом — **CC BY-SA 4.0** на текст KB в репо ([`PUBLISHING.md`](../PUBLISHING.md)); код в других репо — MIT, как сейчас. |
| 109 | |
| 110 | ### 2. Состав репозитория (начальный) |
| 111 | |
| 112 | | Путь | В org-kb? | Примечание | |
| 113 | |------|-----------|------------| |
| 114 | | `agent-notes.md` (до `public-cut` + stub manifest) | да | тот же контракт, что kb-public | |
| 115 | | `knowledge/META/` (integrity, memory-architecture json, …) | да | без секретов | |
| 116 | | `knowledge/worlds/`, `domains/`, шаблоны, router, SHOWCASE, one-pager | да | зона коллаборации | |
| 117 | | `knowledge/work/projects/` | **да** | карточки `project-id`, scope; **без** `C:\`/`D:\` — чеклист [`../work/org/checklist-sanitize-paths-for-org-v1.md`](../work/org/checklist-sanitize-paths-for-org-v1.md) | |
| 118 | | `knowledge/work/org/` | **да** | scope contour map, чеклист санитизации, README; копируется целиком при seed | |
| 119 | | `knowledge/work/local/` | **нет в git** | только `README.md`, `*.example.*`, `.gitignore`; реальные map — у каждого в personal | |
| 120 | | `knowledge/personal/` | **нет** | | |
| 121 | | `knowledge/archive/` | **нет** (или отдельная политика) | | |
| 122 | | `knowledge/adr/` | **частично** | ADR про **продукт KB** — да; операционка с путями — нет или redacted | |
| 123 | | `scripts/` (`build-public-kb.ps1`, `push-public-kb.ps1`, `seed-org-kb.ps1`, `KbTextEncoding.ps1`, `README.md`, `kb-public-root/`, `kb-org-root/`) | **да** | зеркало канона для **canon-maintainer**; SSOT — репо **личного/командного канона** `agent-notes`; в **kb-public** не попадает | |
| 124 | | `knowledge/public-kb.push` | **нет** в org (по умолчанию) | локально у maintainer; шаблон `scripts/public-kb.push.example` | |
| 125 | |
| 126 | Стартовое наполнение: **`scripts/seed-org-kb.ps1`** в каноне (или вручную: output `build-public-kb.ps1` + санитизированный `work/projects/` + корневые шаблоны + копия `scripts/`). |
| 127 | |
| 128 | ### 3. Потоки изменений (governance) |
| 129 | |
| 130 | **Рекомендуемая модель «org-first для shared, federation пар, opt-in canon»:** |
| 131 | |
| 132 | ```mermaid |
| 133 | flowchart LR |
| 134 | subgraph pairs [Pairs A B C] |
| 135 | A[Security PR/export] |
| 136 | B[Psychology PR/export] |
| 137 | C[Other domains] |
| 138 | end |
| 139 | subgraph org [AI-Guiders/kb SSOT shared] |
| 140 | KB[kb collaborative] |
| 141 | end |
| 142 | subgraph owner [Личный канон opt-in] |
| 143 | AN[import / local / export scope] |
| 144 | end |
| 145 | subgraph mirror [Внешнее зеркало] |
| 146 | PUB[kb-public] |
| 147 | end |
| 148 | A --> KB |
| 149 | B --> KB |
| 150 | C --> KB |
| 151 | KB -->|read all| pairs |
| 152 | KB -->|import-from-org-kb| AN |
| 153 | AN -->|export-to-org-kb scoped| KB |
| 154 | AN -->|build-public-kb| PUB |
| 155 | ``` |
| 156 | |
| 157 | - **В org-kb:** прямые PR участников; review (1+ org-maintainer); CODEOWNERS по доменам — по мере роста. |
| 158 | - **В личный канон:** import выбранных paths; личное/пути **не** экспортируются в org без санитизации. |
| 159 | - **Bootstrap в org-kb:** `seed-org-kb.ps1 -Push` или `bootstrap-org-kb.ps1` — **не** routine; затирает весь `knowledge/`. |
| 160 | - **Экспорт scoped:** `export-to-org-kb.ps1` по `knowledge/work/local/group-kb.export` или `-Paths`. |
| 161 | - **Импорт:** `import-from-org-kb.ps1` по `knowledge/work/local/group-kb.import`. |
| 162 | - **Пуш kb-public** — отдельно, canon-maintainer(s). |
| 163 | |
| 164 | **Запрещено по умолчанию:** коммит в org-kb файлов с путями `C:\`, `D:\`, имён собеседников, `work/local/workspace-scope-map` с реальными корнями. |
| 165 | |
| 166 | ### 4. MCP и hot-context |
| 167 | |
| 168 | - Участник клонирует `AI-Guiders/kb`, в MCP: `AGENT_NOTES_CANON_PATH=<clone>`. |
| 169 | - Ожидание: как у kb-public после [008](008-workspace-scope-map-hot-mcp-and-public-cut.md) + stub manifest + `AIGuiders.AgentNotes.Core` ≥ 1.0.1 (`l0` из JSON, `l0_owner` без секций — не грузится). |
| 170 | - Scope: явный `active_scope`, **или** карта в **личном** primary (`work/local/workspace-scope-map-v1.md` при `AGENT_NOTES_CANON_PATH` = личный канон), **или** fallback в коде. Org-клон **без** закоммиченной карты — норма; работа в umbrella-workspace без local map — слабый режим (см. [012](012-multi-canon-workspace-resolution-v1.md)). |
| 171 | |
| 172 | ### 5. Связь с переносом open-репозиториев в org |
| 173 | |
| 174 | - MCP, Core, CIDE, `mcp-tool-manifest` — репозитории **кода** в `AI-Guiders/*`. |
| 175 | - **`AI-Guiders/kb` — репозиторий текста знаний**, не смешивать с `agent-notes-mcp`. |
| 176 | - В README org и в kb: таблица «какой репо за что». |
| 177 | |
| 178 | --- |
| 179 | |
| 180 | ## Последствия |
| 181 | |
| 182 | **Плюсы** |
| 183 | |
| 184 | - Коллаборация без доступа к личному канону. |
| 185 | - Единая точка для «общих линий» и онбординга новых участников org. |
| 186 | - MCP и агенты работают на одном клоне без путаницы с kb-public mirror. |
| 187 | |
| 188 | **Минусы / риски** |
| 189 | |
| 190 | - **Дрейф** org-kb vs **личный канон**, если не зафиксировать import/export ритуал. |
| 191 | - Нужны maintainers и время на review PR. |
| 192 | - Публичность org-kb vs private org — влияет на то, можно ли форкать наружу без второго зеркала. |
| 193 | |
| 194 | --- |
| 195 | |
| 196 | ## План внедрения (если ADR принят) |
| 197 | |
| 198 | 1. ~~Создать `AI-Guiders/kb` (private org + LICENSE CC BY-SA).~~ **Сделано (2026-05-19):** https://github.com/AI-Guiders/kb — bootstrap (smoke, CONTRIBUTING, CODEOWNERS); полный `seed-org-kb.ps1` — позже. |
| 199 | 2. Initial commit = `.\scripts\seed-org-kb.ps1` после `build-public-kb.ps1` и прохода [`checklist-sanitize-paths-for-org-v1.md`](../work/org/checklist-sanitize-paths-for-org-v1.md). |
| 200 | 3. Шаблоны: `scripts/kb-org-root/CONTRIBUTING.md`, `CODEOWNERS`, `knowledge/work/local/.gitignore`. |
| 201 | 4. Runbook: [`runbook-org-kb-federation-v1.md`](../work/projects/door-to-singularity/agent-notes-kb/templates/runbook-org-kb-federation-v1.md) (export/import/bootstrap). |
| 202 | 5. Обновить `public-kb.push` / CI: целевой remote GitHub — **`AI-Guiders/kb-public`** (см. `knowledge/public-kb.push`); org `AI-Guiders/kb` — отдельный контур совместного канона. |
| 203 | 6. Упоминание в `index-knowledge-router-v1.md` (секция router-org-kb) — после стабилизации имени репо. |
| 204 | |
| 205 | --- |
| 206 | |
| 207 | ## Решения (2026-06-12) |
| 208 | |
| 209 | 1. **Имя репозитория:** `kb` — принято. |
| 210 | 2. **kb-public:** внешнее зеркало (вариант C); `AI-Guiders/kb-public` — канонический remote публичной сборки. |
| 211 | 3. **Видимость `AI-Guiders/kb`:** private org (члены org); публичность — через kb-public. |
| 212 | 4. **Кто может писать:** члены org — PR; merge через org-maintainer / CODEOWNERS. |
| 213 | 5. **Обратный поток в канон:** opt-in `import-from-org-kb.ps1`; автоматический merge без review — нет. |
| 214 | 6. **Роли:** org-maintainer (review org) vs canon-maintainer (kb-public, bootstrap) — разделены, можно совмещать. |
| 215 | 7. **ADR в org-kb:** продуктовые ADR из public slice; операционка с путями — redacted или только в каноне. |
| 216 | 8. **Зоны коллаборации:** `worlds/`, `domains/`, scoped `work/projects/`; federation по доменам; full wipe — только bootstrap. |
| 217 | |
| 218 | ## Открытые вопросы (исторические; см. «Решения» выше) |
| 219 | |
| 220 | 1. **Имя репозитория:** `kb` vs `knowledge-base` vs `agent-notes-kb`? |
| 221 | 2. **kb-public на KarataevDmitry:** оставить как **внешнее зеркало** (вариант C), **архивировать** с redirect на `AI-Guiders/kb`, или **только** org-kb? |
| 222 | 3. **Видимость `AI-Guiders/kb`:** public (форки, issues) или private org (только члены)? |
| 223 | 4. **Кто может писать:** все члены org / только команда в CODEOWNERS / ветка `contributors/*`? |
| 224 | 5. **Обратный поток в личный канон:** canon-maintainer вручную, или bot `org-kb → agent-notes` с label `import-candidate`? |
| 225 | 6. **Роли:** **org-maintainer** (review в `AI-Guiders/kb`) vs **canon-maintainer** (скрипты, `public-kb.push`) — совмещать можно, но это разные зоны ответственности. |
| 226 | 7. **ADR в org-kb:** все `knowledge/adr/*.md` из публичного среза или отдельный `adr/` только «продуктовые» без операционных путей? |
| 227 | 8. **Зоны коллаборации:** достаточно `knowledge/worlds/**` + корневые index/playbook, или завести `knowledge/collab/**` для черновиков до промоции в worlds? |
| 228 | |
| 229 | --- |
| 230 | |
| 231 | ## Рекомендация автора ADR (для обсуждения) |
| 232 | |
| 233 | - Репо: **`AI-Guiders/kb`**, public внутри org (или public GitHub, если цель — открытые общие линии). |
| 234 | - **`AI-Guiders/kb-public`:** канонический GitHub remote для публичной сборки kb-public (`public-kb.push`). Старый `KarataevDmitry/kb-public` — редирект GitHub. |
| 235 | - Governance: **PR в org-kb** + периодический **import** в **личный канон**; export script с тем же `public-kb.ignore`. |
| 236 | - В org-kb: `work/projects/` (санитизация путей), не `work/local/` (git), не `personal/`, не hot ниже cut. |
| 237 | |
| 238 | --- |
| 239 | |
| 240 | ## Статус принятия |
| 241 | |
| 242 | **Accepted** 2026-06-12. Federation runbook: [`runbook-org-kb-federation-v1.md`](../work/projects/door-to-singularity/agent-notes-kb/templates/runbook-org-kb-federation-v1.md). |
| 243 | |
| 244 | |