| 1 | # Playbook: авторинг **любого** мира и kb под kb-public (v1) |
| 2 | |
| 3 | **Назначение:** обязательный контракт для **агента и человека** при создании или существенной правке файлов, которые **попадают в публичную сборку** (`build-public-kb.ps1` → kb-public). Это **не** «само собой» — проверять **до коммита**, даже если материал пока только в полном каноне. |
| 4 | |
| 5 | **Область:** **каждый** каталог `knowledge/worlds/<slug>/` — без исключения по домену (`engineering-cad`, `software-dotnet-csharp`, `cognition-language-acquisition`, `medicine-evidence`, `knowledge-engineering`, …). Файл лежит в `knowledge-engineering/` только как **мета-playbook** канона; правило **не** ограничено миром knowledge.engineering. |
| 6 | |
| 7 | **Связано:** [`PUBLISHING.md`](../../PUBLISHING.md) · [`templates/worlds/README.md`](../../templates/worlds/README.md) · [`playbook-kb-operational-freshness-v1.md`](playbook-kb-operational-freshness-v1.md) |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## Когда обязателен |
| 12 | |
| 13 | | Действие | Где | |
| 14 | |----------|-----| |
| 15 | | Новый или расширенный **любой мир** | `knowledge/worlds/<slug>/` — **любой** slug (README, status, playbook, fundamentals, map, troubleshooting A) | |
| 16 | | Новая строка **Domain Entry Map** | `index-knowledge-router-v1.md` (и при необходимости supplement) | |
| 17 | | **Fundamentals / operational** в `worlds/` | `kb-*-fundamentals-v1.md`, `playbook-*-operational-v1.md` | |
| 18 | | Правки **hub** `worlds/README.md`, каталоги миров | любой текст, уходящий в kb-public | |
| 19 | |
| 20 | **Не заменяет:** слой **`work/`** (там **можно** scope, пути, внутренние имена) и **`personal/`** (не публикуется). |
| 21 | |
| 22 | --- |
| 23 | |
| 24 | ## Допущение по умолчанию |
| 25 | |
| 26 | Всё под **`knowledge/worlds/`** (кроме путей из **`public-kb.ignore`**) **будет** скопировано в kb-public. Пиши так, будто файл уже читает внешний человек без доступа к твоему диску и внутренним карточкам. |
| 27 | |
| 28 | **Разделение слоёв:** |
| 29 | |
| 30 | | Слой | Содержание | Публично | |
| 31 | |------|------------|----------| |
| 32 | | **`worlds/<slug>/`** | vendor-neutral предметка: платформы, API-модели, сборка, общие playbooks | **да** | |
| 33 | | **`work/projects/…`** | scope, clone, диск, лицензии команды, runbook репо | **нет** | |
| 34 | | **`personal/`** | личное | **нет** | |
| 35 | |
| 36 | Operational playbook **внутри `worlds/`** описывает **как агент ходит по kb**, а не «где лежит клон на D:\…». |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## Вычистить перед сохранением (чеклист) |
| 41 | |
| 42 | ### 1. Операционка и идентификаторы |
| 43 | |
| 44 | - [ ] Нет **`[SCOPE:…]`**, **`[PRIMARY:…]`**, внутренних **project-id** / codename продуктов (если не общеизвестный публичный продукт вендора). |
| 45 | - [ ] Нет ссылок и отсылок к **`knowledge/work/`**, **`work/projects/`**, «см. карточку в work». |
| 46 | - [ ] Нет **машинных путей** (`D:\…`, `C:\Users\…`, UNC, внутренние FQDN, URL Confluence/wiki команды). |
| 47 | - [ ] Нет **ConnStr**, токенов, ключей лицензий, имён внутренних SQL/серверов. |
| 48 | |
| 49 | ### 2. Бренды и имена |
| 50 | |
| 51 | | Можно | Нельзя (в `worlds/`) | |
| 52 | |-------|----------------------| |
| 53 | | Публичные **вендоры и платформы** (Autodesk, AVEVA, Tekla, Microsoft, Nanosoft, …) | Внутренние кодовые имена линейки продуктов, employer-specific стеки | |
| 54 | | Открытые **стандарты**, NuGet, публичные API-имена | Клиенты, заказчики, внутренние монорепо без публичного имени | |
| 55 | | Общеизвестные **open-source** проекты по делу | «Наш продукт X», unless X is genuinely public brand | |
| 56 | |
| 57 | При сомнении: **обобщить** («multi-CAD plugin repository», «managed addin») или вынести в **`work/`**. |
| 58 | |
| 59 | ### 3. Роутер и hub |
| 60 | |
| 61 | - [ ] В **Domain Entry Map** нет колонки «диск» / путей к `work/`. |
| 62 | - [ ] В **README мира** нет блока «указатель на work» — только фраза, что clone/диск **вне kb** (без пути в дереве канона). |
| 63 | |
| 64 | ### 4. Слой operational vs fundamentals |
| 65 | |
| 66 | - [ ] **Fundamentals** — определения, anti-patterns, vendor docs; без «как у нас в SSCADRepo». |
| 67 | - [ ] **Operational в `worlds/`** — порядок загрузки kb, Roslyn, verify; без привязки к частному workspace. |
| 68 | |
| 69 | --- |
| 70 | |
| 71 | ## Процедура агента (кратко) |
| 72 | |
| 73 | 1. Создать/править по шаблонам **`templates/worlds/`**. |
| 74 | 2. Пройти чеклист § «Вычистить» (включая `grep` по новому каталогу: `work/`, `SCOPE:`, `D:\\`, внутренние codename). |
| 75 | 3. При новом миру — обновить **router** без operational-хвостов. |
| 76 | 4. Перед пушем в публичное зеркало (если maintainer): **`scripts/build-public-kb.ps1`** и выборочно просмотреть `dist/public-kb/knowledge/worlds/<slug>/`. |
| 77 | 5. Внутреннюю operationalку (scope, clone, license governance) — только **`work/projects/<scope>/`**. |
| 78 | |
| 79 | --- |
| 80 | |
| 81 | ## Anti-patterns |
| 82 | |
| 83 | - «Уберём URSA в следующем коммите» — **сразу** писать нейтрально в `worlds/`. |
| 84 | - Дублировать в fundamentals то, что уже в **`work/`**, «чтобы агенту было удобнее» — агент в полном каноне читает work отдельно. |
| 85 | - Ссылаться на **`work/`** в публичном тексте «для полноты» — в kb-public ссылка битая и раскрывает структуру private-слоя. |
| 86 | - Класть **`playbook-*-operational`** в `worlds/` с содержанием clone/scope — такой operational → в **`work/`** или сузить до kb-only. |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Links |
| 91 | |
| 92 | | Нужно | Файл | |
| 93 | |--------|------| |
| 94 | | Исключения путей | `knowledge/public-kb.ignore` | |
| 95 | | Политика публикации | `PUBLISHING.md` | |
| 96 | | Шаблоны миров | `templates/worlds/` | |
| 97 | | One-pager | `kb-one-pager-structure-and-protocols-v1.md` § Публикация | |
| 98 | |
| 99 | **Версия:** v1.1 · 2026-06-05 |
| 100 | |
| 101 | |