@7n/rules 1.0.0

package/rules/ci4/main.mdc

@@ -0,0 +1,375 @@
+---
+description: Архітектурна документація продукту — Markdown як джерело істини; рекомендований стек arc42 + Diátaxis + ADR (MADR v4, формат описаний у правилі `adr`) + C4 як набір нотацій; гібридна модель manual + autogen-зон, що регенеруються з accepted ADR; Zed + marksman LSP як viewer без site-generator-а, portable subset (CommonMark + GFM + Mermaid + KaTeX), collapsible engineer-блоки через нативний `<details>`; рекомендоване VSCode-розширення `arr.marksman` для контрибʼюторів поза Zed; `.marksman.toml` авто-створюється у корені проєкту з canonical baseline
+alwaysApply: true
+version: '3.2'
+---
+
+Архітектурна документація проєкту живе у Markdown поряд із кодом — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед будь-якою зміною коду. Правила нижче — не оформлення, а робочий процес: який стек використовуємо, як зберігаємо рішення, як автоматично перегенеровуємо проекції з ADR і як рендеримо для змішаної аудиторії (менеджери + інженери + ops). Формат самих ADR-файлів — MADR v4.0.0 minimal — описаний у правилі **`adr`** (`npm/rules/adr/adr.mdc`).
+
+## Markdown як джерело істини
+
+Уся ключова інформація про проєкт — архітектура, рішення (ADR), тести й документація — зберігається у `.md`/`.mdc`-файлах і є **офіційним джерелом істини**. Це єдиний спосіб тримати знання разом із кодом — версійно, в одному PR і доступно для агентів. Якщо щось важливе про систему існує лише у Confluence/Notion/месенджері — для проєкту цього **немає**.
+
+## Специфікація як джерело істини (Spec-as-Source)
+
+У AI-native розробці первинним артефактом, який підтримують інженери, є **специфікація**, а не кодова база. Код — похідний артефакт, «будівельне риштування», яке агент генерує, верифікує або повністю відновлює зі специфікації. Якщо поведінка системи має змінитися — **спочатку оновлюємо специфікацію (arc42-розділ, ADR, опис компонента), і лише потім** агент генерує відповідний код. Зворотний порядок («код вже написаний, доку напишемо потім») перетворює специфікацію на декорацію.
+
+## Тест на повне відтворення (Rebuild Test)
+
+Документація вважається повною лише тоді, коли проходить бінарний тест: якщо видалити теку `src/`, відкрити нову LLM-сесію з чистим контекстом і дати агенту доступ лише до `.md`-файлів — агент має **відтворити робочу кодову базу**. Архітектурні збої (агент не знає структуру тек), інтеграційні (неописані міжсервісні контракти), падіння юніт-тестів (неописана бізнес-логіка) — це не «складність задачі», а **прогалини документації**, які треба заповнити у тому ж PR.
+
+## Ефективність токенів і чистий Markdown
+
+Вікно контексту LLM обмежене, а якість міркування деградує в міру його заповнення (ефект «Lost in the Middle»). Тому документація **очищається від HTML-розмітки, CSS-класів, навігаційних обгорток** і всього, що не несе семантичного навантаження. Чистий Markdown замість HTML економить 80–90 % токенів (≈16 000 → 1 600 на сторінку), що прямо впливає на точність згенерованого коду і знижує вартість API. Жодних `<div>`/`<span>`/класів у тілі `.md`/`.mdc`. Єдиний виняток — HTML-коментарі-маркери AUTOGEN-зон, які не рендеряться у viewer і несуть службову інформацію для генератора (`<!-- AUTOGEN:start ... -->`).
+
+## Контекстна незалежність розділів
+
+RAG витягує **фрагменти**, не цілі документи. Тому кожен розділ має сенс **без сусіднього тексту**. Заборонено: «як було згадано вище», «ця змінна», «попередній метод», «той самий сервіс». Замість цього — щоразу явно повторюємо назву сутності: «автентифікація OAuth 2.0», «функція `calculateTotal()`», «контейнер `api-gateway`». Коли агент отримає лише цей фрагмент, у нього має бути повний словник для коректної генерації.
+
+## Docs-as-Code
+
+Документація живе у Git поруч із кодом, проходить **той самий Code Review**, версіонується і автоматично перевіряється у CI (лінтери Markdown, валідатори посилань, `npx @7n/rules fix`). Биті посилання й документація, що «не компілюється», — **блокуючий баг**, не косметика.
+
+## Трасування як документація недетермінованої поведінки
+
+Для компонентів, де рішення приймає нейромережа або складна евристика, класичної форми «вхід X → вихід Y» **недостатньо** — поведінка недетермінована. Джерелом істини стає **пайплайн логування й трасування**: які інструменти використав агент, який контекст мав, чому ухвалив це рішення. У описі компонента такого типу — посилання на дашборд/storage трасувань обов'язкове нарівні з посиланнями на тести.
+
+## Рекомендований стек
+
+Беремо **завжди**:
+
+- **arc42** — скелет документа архітектури. 12 розділів із природним розподілом аудиторій: 1-3 (Introduction, Constraints, Context) — менеджерська проза, 5-9 (Building Blocks, Runtime, Deployment, Crosscutting, Decisions) — інженерні. Розділ 9 «Architecture Decisions» — індекс ADR.
+- **Diátaxis** — мета-структура сайту документації: tutorials / how-to / reference / explanation. arc42 живе в `explanation/`. Для більшості продуктів tutorials опціональні; реально потрібні explanation + reference + how-to.
+- **ADR (MADR v4.0.0 minimal)** — append-only event log архітектурних рішень. Формат, фази capture/normalize, Stop-hook автоматика описані у правилі **`adr`**. Clean ADR-файл — `docs/adr/<slug>.md` без frontmatter, з англомовними MADR-заголовками і `**Status:** Accepted` / `**Date:** YYYY-MM-DD` рядками. Це єдине джерело правди для регенерації проекцій.
+- **C4 model** — як набір нотацій для діаграм усередині arc42: контекстна (C4 рівень 1) і контейнерна (рівень 2) у `explanation/architecture.md`, компонентна (рівень 3) — на сторінках компонентів. Не самостійна метамодель, а інструмент візуалізації.
+
+Доповнюємо **під domain**:
+
+- **DDD Context Maps** — коли є >1 bounded context (типово для multi-agent: agents, orchestration, memory, tooling). Одна Mermaid-діаграма в `explanation/architecture.md`, ховається під `<details><summary><strong>Engineer:</strong> Context Map</summary>`.
+- **EventModeling** — для event-driven систем (агентські pipeline, CQRS, Event Sourcing). Структура: trigger → command → event → read model. Читається менеджером як наратив, інженером — як креслення.
+- **Business Capability Map** — верхньорівневий manager-overview. Autogen через семантичну класифікацію accepted ADR за тематикою.
+- **Wardley Map** — стратегічний артефакт для board/інвесторів. Manual, не autogen. Квартальне оновлення. Живе в `explanation/strategy.md`.
+
+**Не використовуємо** для product docs:
+
+- 4+1 View Model, Viewpoints & Perspectives — academic/enterprise, дублюють arc42.
+- ISO/IEC/IEEE 42010 — мета-стандарт без шаблонів.
+- UML повністю — беремо точково Mermaid (Sequence, Component, Deployment) всередині arc42.
+- Service Blueprint, Value Stream Mapping, JTBD, Impact Mapping, User Story Mapping — planning/UX інструменти, не docs.
+- EventStorming, Domain Storytelling — workshop-формати; артефакт з них конвертується в EventModeling або Context Map.
+
+## Структура репозиторію
+
+```
+docs/
+├── adr/
+│   ├── <slug>.md                       # clean ADR-и (MADR v4 minimal, без frontmatter)
+│   ├── YYMMDD-HHMM-<sid>.md            # drafts (frontmatter session:/captured:/transcript:)
+│   └── index.md                        # autogen — список accepted ADR за датою
+├── explanation/                        # Diátaxis: чому і що
+│   ├── overview.md                     # Capability Map (autogen)
+│   ├── architecture.md                 # arc42 + Context Map + EventModeling + C4 діаграми
+│   ├── strategy.md                     # Wardley Map (MANUAL)
+│   └── components/                     # сторінки на компонент
+├── reference/                          # API, конфіги, схеми
+├── how-to/                             # runbooks, інтеграції
+├── snapshots/                          # періодичні зрізи
+└── .docgen/
+    ├── config.yaml
+    ├── prompts/                        # системні промпти LLM
+    └── manifest.json                   # реєстр зон, ADR-slug → зони
+```
+
+Інших місць для архітектурних схем у репозиторії немає: розпорошення по підтеках сервісів ламає навігацію «від системи вглиб» і робить агентський аналіз перед зміною дорожчим. Структуру drafts і clean ADR у `docs/adr/` створює і підтримує автоматика правила **`adr`** — окремий формат тут не визначаємо.
+
+## ADR як вхід проекцій
+
+Регенератор працює **тільки з clean ADR** (`docs/adr/<slug>.md`, без frontmatter, з рядком `**Status:** Accepted`). Drafts (`YYMMDD-HHMM-*.md`) ігноруються — їх перетворить у clean ADR `normalize-decisions.sh` із правила `adr`.
+
+Поля, які регенератор читає з clean ADR:
+
+- **Slug** — ім'я файлу без `.md`, використовується як ідентифікатор у маркерах і `manifest.json`.
+- **Status** — рядок `**Status:** Accepted` у тілі. ADR з іншим статусом (або без рядка) у проекції не потрапляє.
+- **Date** — рядок `**Date:** YYYY-MM-DD`, для впорядкування і відображення у проекції.
+- **Heading H1** — перший `#`-заголовок, як назва рішення.
+- **Розділи MADR** — `## Context and Problem Statement`, `## Considered Options`, `## Decision Outcome`, `### Consequences`, `## More Information`. Для проекції зазвичай беруться Decision Outcome + Consequences.
+- **`## Update YYYY-MM-DD`** — appended-секції у тому ж файлі. Враховуються як еволюція рішення в хронологічному порядку.
+
+**Маршрутизація ADR → зони** робиться двома способами:
+
+1. **Explicit** — у самій AUTOGEN-зоні в атрибуті `sources` перелічені slug-и: `sources="ланцюжок-запуску-abie,npm-publish-flow"`. Це єдиний робочий механізм у MADR v4 minimal (frontmatter `affects:` поля немає).
+2. **Discovery** — семантичний індекс: ембеддинги розділів `## Context and Problem Statement` + `## Decision Outcome` кожного ADR; зона декларує тематику, регенератор підтягує top-K релевантних slug-ів. Використовується для оглядових проекцій (`overview.md`, Capability Map).
+
+## Документація як derived state від ADR
+
+Документація = **derived state** від ADR. Інженер ніколи не редагує autogen-тексти вручну — тільки через ADR. Якщо потрібно щось виправити в проекції — це означає, що або є accepted ADR, який треба еволюціонувати через `## Update YYYY-MM-DD` (механіка з правила `adr`), або є некоректний промпт у `docs/.docgen/prompts/`, або взагалі потрібен новий ADR.
+
+## Гібрид manual + autogen
+
+Реальні проєкти мають legacy docs, написані до появи ADR. Розв'язок — **зони** через HTML-коментарі (виживають у Markdown, не рендеряться у жодному MD viewer — ні в Zed built-in preview, ні на GitHub, ні в будь-якому майбутньому site-generator-і):
+
+```markdown
+# User Service
+
+User Service відповідає за автентифікацію та профілі.
+*Цей абзац — manual, LLM не чіпає.*
+
+<!-- AUTOGEN:start id="user-service-decisions" hash="sha256:a1b2c3..." sources="ланцюжок-запуску-abie,npm-publish-flow,oidc-pkce-flow" -->
+## Ключові рішення
+
+Сервіс працює на Bun runtime [npm-publish-flow]. Автентифікація — OIDC з PKCE
+[oidc-pkce-flow]. Запуск організовано через [ланцюжок-запуску-abie].
+<!-- AUTOGEN:end id="user-service-decisions" -->
+
+## Історичний контекст
+Сервіс виник у 2023 як частина моноліту...
+```
+
+Типи зон:
+
+- **`AUTOGEN`** — повністю від ADR, регенерується з нуля. Hash перевіряється строго.
+- **`MANUAL`** (default — усе поза маркерами) — LLM не торкається. Опційно явні маркери `<!-- MANUAL:start id="..." -->` для документації наміру.
+- **`MERGED`** — LLM отримує існуючий manual + ADR, робить узгоджене оновлення. Найризикованіший, на старті уникати.
+
+**Backfill legacy:** поступово витягуйте архітектурні знання з manual-текстів у retroactive ADR. Не одразу — тільки коли торкаєтесь області. Природна еволюція: manual → новий accepted ADR (через звичайний capture-flow) → manual замінюється AUTOGEN-зоною з посиланням на slug.
+
+## Manifest з інвертованим індексом
+
+`docs/.docgen/manifest.json`:
+
+```json
+{
+  "zones": {
+    "user-service-decisions": {
+      "file": "explanation/components/user-service.md",
+      "sources": ["ланцюжок-запуску-abie", "npm-publish-flow", "oidc-pkce-flow"],
+      "content_hash": "sha256:...",
+      "generated_at": "2026-05-17T10:32:00Z",
+      "generator_version": "v3"
+    }
+  },
+  "adr_index": {
+    "ланцюжок-запуску-abie": {
+      "affects_zones": ["user-service-decisions", "startup-overview"],
+      "status": "Accepted",
+      "date": "2026-04-12",
+      "updates": ["2026-05-03"]
+    }
+  }
+}
+```
+
+Інвертований індекс `adr_index` критичний: коли accepted ADR отримує `## Update YYYY-MM-DD`, регенератор миттєво знає, які зони ререндерити без сканування всіх файлів. Hash зони захищає від тихої перезаписки ручних правок: якщо вміст у файлі не збігається з hash у manifest — генератор зупиняється і вимагає рішення людини.
+
+## Цикл оновлення
+
+```
+1. Інженер/менеджер читає docs/
+2. Просить LLM: «хочу змінити X»
+3. LLM:
+   a. знаходить релевантні clean ADR (за slug у sources зон + семантичним пошуком)
+   b. формулює draft-рішення (буде підхоплене capture-decisions.sh як ADR-чернетка)
+   c. показує impact: які зони зміняться після прийняття
+4. Після завершення сесії capture-decisions.sh пише draft у docs/adr/
+5. Коли поріг ADR_NORMALIZE_THRESHOLD досягнуто (або /n-adr-normalize вручну):
+   normalize-decisions.sh перетворює draft → clean ADR <slug>.md з **Status:** Accepted
+6. Регенератор:
+   a. читає clean ADR з **Status:** Accepted (інші ігнорує)
+   b. для кожної AUTOGEN-зони збирає relevant ADR (sources= + discovery)
+   c. перевіряє hash зони — якщо контент != hash, STOP (хтось редагував вручну)
+   d. викликає LLM з промптом проекції
+   e. замінює вміст між маркерами, оновлює hash і adr_index у manifest
+7. Валідатор (детермінований, без LLM)
+8. Git commit з ADR + regenerated docs
+```
+
+**Full rebuild vs incremental:**
+
+- **Full rebuild** (рекомендовано на старті): LLM отримує всі clean ADR зі `**Status:** Accepted` + шаблон — видає документ з нуля. Zero drift.
+- **Incremental**: LLM отримує поточний doc + новий ADR (або `## Update`) — видає diff. Дешевше, але дрейф накопичується.
+- **Компроміс**: incremental + періодичний full rebuild (раз на місяць або після N нових ADR).
+
+## Viewer/editor: Zed + marksman LSP
+
+Окремого site-generator-а **немає** — каталог `docs/` сам є інтерфейсом читання. Інженер відкриває `.md`-файл у Zed і одразу бачить рендер через built-in preview (`cmd+shift+m`). Між сторінками рухається через **`marksman`** LSP: `cmd+click` по `[link](file.md)` і `[[wiki-link]]`, автокомпліт заголовків, find-references, refactor-перейменування заголовків з оновленням посилань у всьому `docs/`.
+
+`~/.config/zed/settings.json`:
+
+```json
+{
+  "languages": {
+    "Markdown": {
+      "language_servers": ["marksman"],
+      "soft_wrap": "editor_width"
+    }
+  }
+}
+```
+
+Деталі конфігурації `.marksman.toml` та VSCode-альтернативи — у відповідних секціях нижче.
+
+**Portable-only синтаксис.** Усе, що пишемо в `docs/`, обмежене **CommonMark + GFM + Mermaid у fenced code (` ```mermaid `) + KaTeX (`$...$`) + нативний HTML5 `<details>`**. Заборонено:
+
+- pymdownx admonitions (`!!! note`, `??? engineer`, `=== "tab"`)
+- VitePress containers (`::: tip`, `::: details`)
+- MDX/Astro-компоненти (`<MyComponent />`)
+- Hugo shortcodes (`{{< youtube id >}}`)
+- AsciiDoc-вкраплення, RST-директиви
+
+Усе вище не рендериться у Zed built-in preview і ламає головний принцип: **«відкрив файл = побачив фінальний вигляд»**. Обмеження **forward-compatible**: portable subset рендериться у GitHub, MkDocs, VitePress, Antora — підключення збирача в майбутньому не потребує переписування контенту.
+
+## Collapsible-блоки для змішаної аудиторії
+
+Менеджер читає прозу зверху, інженер розгортає деталі. Реалізація — нативний HTML5 `<details>` / `<summary>`, що рендериться **скрізь**: Zed preview, GitHub, будь-який майбутній збирач. Жодних розширень парсера не треба.
+
+```markdown
+User Service автентифікує користувачів і керує профілями.
+Підтримуємо OIDC-логін та email/password.
+
+<details>
+<summary><strong>Engineer:</strong> Технічна реалізація автентифікації</summary>
+
+OIDC-сервер на Fastify з PKCE flow [oidc-pkce-flow].
+Refresh-токени з rotation, TTL 30 днів, Redis storage.
+
+</details>
+
+Профілі зберігаються в основній БД, кешуються в Redis на 5 хв.
+
+<details>
+<summary><strong>Ops:</strong> Деталі кешу та інвалідації</summary>
+
+Cache key: `user:profile:{userId}:v2`.
+Інвалідація — NATS подія `user.profile.updated` [user-profile-events].
+
+</details>
+```
+
+**Конвенція маркера у `<summary>`:** перше слово — аудиторія з фіксованого словника (`Engineer:`, `Ops:`, `Security:`, `Manager:`), далі — описова назва. Це дає валідатору детермінований regex для перевірок типу «жоден `Engineer:`-блок не з'являється в manager-only проекціях».
+
+**Технічні нюанси `<details>`:**
+
+- порожній рядок до `<details>` і після `<summary>` обов'язковий — інакше Markdown-парсер не активує блочний рендер усередині
+- за замовчуванням блок згорнутий; `<details open>` — розгорнутий
+- візуальна типізація аудиторій робиться **через текст `<summary>`**, не через CSS — у Zed preview кастомні стилі недоступні
+- `<details>` ≠ HTML-обгортка з правила «жодних `<div>`/`<span>`»: це **семантичний** HTML5-елемент, а не презентаційний; його token-cost мізерний
+
+## Промпт для LLM-проекцій
+
+Тримати у `docs/.docgen/prompts/projection.md` як артефакт першого класу — версіонується, ревʼюється, тестується на golden-наборі ADR. Скелет:
+
+```
+Ти пишеш документацію для змішаної аудиторії (менеджери + інженери).
+
+Структура кожної секції:
+1. 2-4 речення прози рівня менеджера: що це робить, яку цінність дає,
+   як пов'язано з іншими частинами продукту. Без технологій, версій, коду.
+
+2. Технічні деталі — тільки всередині блоків:
+   <details>
+   <summary><strong>Engineer:</strong> Описова назва блоку</summary>
+
+   Код, конфіги, версії, посилання на ADR.
+
+   </details>
+
+3. Operational деталі:
+   <details>
+   <summary><strong>Ops:</strong> Що моніторити та як реагувати</summary>
+
+   Метрики, алерти, runbook-кроки.
+
+   </details>
+
+Правила:
+- Якщо прибрати всі <details>-блоки, текст лишається зв'язним менеджерським документом.
+- Перше слово у <summary> — аудиторія з фіксованого словника
+  (Engineer:/Ops:/Security:/Manager:), далі — описова назва
+  (наприклад «<strong>Engineer:</strong> Чому Percona, а не MariaDB»).
+- Порожній рядок до і після вмісту <details> обов'язковий.
+- Кожен факт з ADR маркуй [<slug>] всередині <details>-блоку — slug це ім'я clean ADR
+  без розширення (наприклад `[ланцюжок-запуску-abie]`).
+- НЕ виходь за межі <!-- AUTOGEN:start --> ... <!-- AUTOGEN:end -->.
+- ADR без рядка `**Status:** Accepted` ігноруй.
+- Якщо в ADR є `## Update YYYY-MM-DD` секції — враховуй найсвіжіший стан рішення,
+  старі формулювання вважай застарілими.
+- Заборонені framework-specific synaxes: !!! note, ??? engineer, ::: tip,
+  MDX-компоненти, Hugo shortcodes — тільки CommonMark + GFM + Mermaid + <details>.
+```
+
+## Типові поломки LLM і захист
+
+| Проблема                     | Захист                                                                                    |
+| ---------------------------- | ----------------------------------------------------------------------------------------- |
+| Галюцинація деталей          | Правило `[<slug>]` маркера + post-gen linter, що перевіряє існування `docs/adr/<slug>.md` |
+| Втрата `## Update`-еволюції  | Pre-process: збирати всі `## Update YYYY-MM-DD` у ADR, передавати у промпт як патчі       |
+| Дрейф термінології           | `docs/glossary.md` як перший вхід у кожен промпт                                          |
+| Перенасичення контексту      | Двостадійна генерація: спочатку summary кожного ADR (кеш), потім проекція                 |
+| Inconsistency між проекціями | Cross-projection validator порівнює факти між документами                                 |
+
+## Валідатор (обов'язково)
+
+Окремий детермінований прохід після регенерації, **без LLM**. Bun-скрипт на ~100-200 рядків, запускається як pre-commit hook:
+
+- Усі `[<slug>]` посилання вказують на існуючі файли `docs/adr/<slug>.md` із рядком `**Status:** Accepted`
+- Усі `AUTOGEN:start` мають парний `AUTOGEN:end` з тим самим `id`
+- Hash у `manifest.json` відповідає фактичному контенту зон
+- Жоден `<details>`-блок з `<summary>` що починається на `Engineer:` / `Ops:` / `Security:` не з'являється в manager-only проекціях
+- Кожен `<details>` має оточуючі порожні рядки (інакше `<summary>`-вміст рендериться як plain HTML, не collapsible)
+- У `docs/` немає заборонених framework-specific конструкцій: `!!! note`, `???`, `::: tip`, `::: details`, MDX-теги `<[A-Z][a-zA-Z]*`, Hugo shortcodes `{{<`
+- Усі inter-doc посилання працюють для `marksman` LSP (відносні шляхи `[text](./other.md)` або `[[wiki-link]]`, не absolute URLs усередині `docs/`)
+- Якщо в зоні згадано компонент — він є в `docs/glossary.md`
+- ADR без `**Status:** Accepted` не потрапили у проекцію
+
+Без валідатора накопичується тихий дрейф: посилання гниють, hash розходиться з контентом, термінологія дрейфує.
+
+## Аналіз перед зміною
+
+Перш ніж вносити зміни в код, агент **читає відповідні docs**: контекст, контейнери, компоненти тієї ділянки, до якої входить редагований код, плюс accepted ADR за тематикою області (`docs/adr/<slug>.md` зі `**Status:** Accepted`). Без цього кроку легко зламати приховані залежності між сервісами або «загубити» зовнішню інтеграцію, описану в `explanation/architecture.md`.
+
+## Оновлення синхронно зі змінами
+
+Кожна зміна, що впливає на архітектуру — нова інтеграція, новий компонент, перейменування, зміна напрямку залежності, видалення сервісу — **супроводжується новим ADR (або `## Update YYYY-MM-DD` у наявному) і регенерацією проекцій у тому ж PR**. Документація не оновлюється «потім» окремою задачею: розсинхрон між кодом і моделлю — найчастіша причина, чому архітектурні документи перестають читати. Capture/normalize flow з правила `adr` забезпечує саму появу ADR — регенерацію проекцій ініціює окремий hook (наприклад, post-merge або `/regen-docs`).
+
+## Зв'язок із ADR
+
+ADR (`docs/adr/<slug>.md`) — джерело правди для autogen-проекцій. Маршрутизація «ADR → зони, на які впливає» виконується через `sources="<slug>,<slug>"` атрибут у самій AUTOGEN-зоні та через семантичний discovery (ембеддинги розділів `## Context and Problem Statement` + `## Decision Outcome`). Поля `affects.components` у frontmatter немає за визначенням MADR v4 minimal — маршрутизація навмисно винесена у зону, а не вшита в ADR, щоб ADR лишався читабельним як автономний документ.
+
+## Зв'язок із тестами
+
+Кожен опис компонента в `explanation/components/<name>.md` має **посилання на відповідні тести** — інтеграційні, e2e або юніт залежно від рівня. Так перехід «компонент → як його перевіряємо» займає один клік, а не пошук по репозиторію. Для агентських компонентів додаткове посилання на storage трасувань — нарівні з тестами, бо без них недетермінована поведінка непідтверджена.
+
+## Зв'язок із документацією
+
+Архітектурні артефакти — частина **користувацької документації**, а не закритий артефакт для команди. Контекстна діаграма (C4 рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у проєкт — у `explanation/architecture.md`, не у відокремленій теці «for-architects». Нативний `<details>`-блок дає collapsible-вигляд у будь-якому MD-viewer (Zed built-in preview, GitHub web UI, потенційний майбутній site-generator) без залежності від конкретного фреймворку — менеджер бачить прозу, інженер розгортає деталі.
+
+## Зв'язок із `.cursor/rules`
+
+`.cursor/rules/*.mdc` — джерело правди для **операційних правил** проєкту: як запускати лінт і тести, як оформлювати CHANGELOG, як версіонувати модулі, які прапорці передавати інструментам тощо. Архітектурна документація у `docs/` **не дублює** ці правила і не переказує їх своїми словами. Дублікат миттєво розходиться з оригіналом, ламає механіку automatic-перевірок (`npx @7n/rules fix`/`check`) і вимагає двох правок при кожній зміні — одна з них неминуче пропускається.
+
+Замість дублювання — **відсилка** на конкретне правило через його ім'я у бектиках: «див. правило **`changelog`**», «див. **`n-lint`**», «деталі формату — у правилі **`adr`**». Відсилка веде читача (людину чи LLM-агента) до єдиного джерела істини; коли правило еволюціонує, документація лишається коректною без правки. Якщо `.cursor/rule` потребує доповнення або уточнення — оновлюй сам `.mdc`, а не копіюй його зміст у `docs/`.
+
+## Інструменти
+
+- **Claude Code** як runner — slash-команда `/regen-docs` або post-commit hook на зміни `docs/adr/**`
+- **capture-decisions.sh** + **normalize-decisions.sh** — Stop-hooks створення ADR (керує правило `adr`)
+- **gray-matter** на Bun — лише для парсингу draft frontmatter; clean ADR парситься regexp по `**Status:**` / `**Date:**`
+- **Zed** як viewer/editor — built-in MD preview (`cmd+shift+m`) рендерить кожен файл без site-generator-а; `<details>` для collapsible-блоків
+- **marksman** LSP як шар навігації — `cmd+click` по `[text](file.md)`/`[[wiki-link]]`, find-references, refactor-перейменування заголовків
+- **Mermaid** для C4-діаграм, EventModeling, Context Maps — рендериться у Zed preview напряму з ` ```mermaid ` fenced code, без розширень
+- **KaTeX** (опційно) — інлайн-математика `$...$` для метрик/формул; рендериться у Zed preview
+- Site-generator (MkDocs Material / VitePress / Antora) — **не використовується**; portable subset гарантує, що його можна підключити пізніше без переписування контенту
+
+## Query mode як бонус
+
+Поверх проекцій — інтерактивний RAG над clean ADR. Інженер питає: «чому ми обрали Percona замість MariaDB?». LLM шукає по semantic index `Context and Problem Statement + Decision Outcome`, повертає `docs/adr/<slug>.md` з прямою цитатою. Корпус малий (десятки-сотні clean ADR після normalize) і структурований (фіксовані MADR-заголовки) — дешево й точно, без галюцинацій.
+
+## Швидкий gate через conftest
+
+Rego-перевірки, що запускаються через `conftest` у фазі `check`:
+
+| Пакет                       | Що перевіряє                                                        |
+| --------------------------- | -------------------------------------------------------------------- |
+| `ci4.vscode_extensions`     | `.vscode/extensions.json` містить `arr.marksman` у `recommendations` |
+
+- [extensions.json.snippet.json](./vscode_extensions/template/extensions.json.snippet.json)

package/rules/ci4/marksman_config/concern.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "lint": { "scope": "full", "glob": [".marksman.toml"] }
+}

package/rules/ci4/marksman_config/data/marksman_config/marksman.baseline.toml

@@ -0,0 +1,27 @@
+# Workspace-маркер marksman LSP. У корені репо робить весь монорепо одним
+# marksman-workspace — README.md і docs/ перехресно навігуються через
+# [text](file.md) і [[wiki-link]]. Файли .mdc не індексуються — marksman
+# дивиться лише на розширення нижче.
+#
+# Створюється правилом ci4 (npx @nitra/cursor fix ci4) із canonical baseline.
+# Ручні правки не перетираються: повторні прогони ідемпотентні (no-op).
+
+[core]
+markdown.file_extensions = ["md", "markdown"]
+
+# GitHub-Flavored Markdown (таблиці, todo, alerts, math) — наш portable subset.
+markdown.glfm = true
+
+[completion]
+# Стиль резолву [[wiki-link]]:
+#   "file-stem"      → [[oidc-pkce-flow]] резолвиться у docs/adr/oidc-pkce-flow.md
+#   "title-slug-ref" → резолв за slugified H1 заголовком
+# Беремо file-stem: ADR-slug == ім'я файла, стабільний ідентифікатор у
+# AUTOGEN sources, manifest, валідаторі. Заголовок може мінятися — посилання
+# не ламається.
+wiki.style = "file-stem"
+
+[code_action]
+# Code action "Insert/Update TOC" — корисно для довгих arc42-сторінок
+# (architecture.md з 12 розділами).
+toc.enable = true

package/rules/ci4/marksman_config/docs/fix-marksman_config.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: fix-marksman_config.mjs
+resource: npm/rules/ci4/marksman_config/fix-marksman_config.mjs
+docgen:
+  crc: 39e3c9a4
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл забезпечує наявність конфігурації Marksman у робочому середовищі, автоматично копіюючи канонічний базовий файл `.marksman.toml` без використання LLM, якщо конфігурація відсутня. Функція `patterns` надає набір правил для подальшого автоматичного виправлення (ci4.mdc).
+
+## Поведінка
+
+1. Визначається набір правил `patterns` для автоматичного виправлення конфігурації Marksman.
+2. Перевіряється, чи відсутня конфігурація Marksman.
+3. Якщо конфігурація відсутня, створюється файл конфігурації Marksman за допомогою копіювання канонічного базового файлу `ci4.mdc` у робочу директорію.
+4. Фіксується, що файл конфігурації був створений із канонічного базового файлу `ci4.mdc`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/ci4/marksman_config/docs/main.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/ci4/marksman_config/main.mjs
+docgen:
+  crc: c34fa8be
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Оновлений текст секції «overview» (як вимагається, без попередньої преамбули та згідно з інструкціями):
+
+Це файловий модуль відповідає за забезпечення певної функціональної області системи. Він виконує аналіз даних у межах визначених логічних кордонів. У своїй поведінці він обов'язково включає маркери повідомлень згідно з `ci4.mdc`.
+
+## Поведінка
+
+1. Викликається функція main.
+2. Перевіряється наявність канонічного baseline-файлу у шляху, відносно розташування поточного файлу.
+3. Якщо baseline-файл не знайдено, видається повідомлення про помилку (ci4.mdc) та процес завершується з відповідним кодом виходу.
+4. Перевіряється наявність цільового файлу .marksman.toml у корені проєкту.
+5. Якщо цільовий файл існує, видається повідомлення про успіх, і процес завершується з кодом виходу 0.
+6. Якщо цільовий файл не існує, канонічний baseline-файл копіюється у цільовий файл .marksman.toml у корені проєкту, і видається повідомлення про успіх (ci4.mdc).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/ci4/marksman_config/fix-marksman_config.mjs

@@ -0,0 +1,24 @@
+/**
+ * T0-autofix для `ci4/marksman_config` — копіює canonical baseline `.marksman.toml` без LLM.
+ */
+import { copyFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { MARKSMAN_BASELINE_PATH, MARKSMAN_TARGET_FILENAME } from './main.mjs'
+
+/** @type {import('../../../scripts/lib/lint-surface/types.mjs').T0Pattern[]} */
+export const patterns = [
+  {
+    id: 'ci4-marksman-config-missing',
+    test: violations => violations.some(v => v.data?.kind === 'marksman-config-missing'),
+    apply: async (_violations, ctx) => {
+      const target = join(ctx.cwd, MARKSMAN_TARGET_FILENAME)
+      ctx.recordWrite?.(target)
+      await copyFile(MARKSMAN_BASELINE_PATH, target)
+      return {
+        touchedFiles: [target],
+        message: `${MARKSMAN_TARGET_FILENAME} створено з canonical baseline (ci4.mdc)`
+      }
+    }
+  }
+]

package/rules/ci4/marksman_config/main.mjs

@@ -0,0 +1,38 @@
+/** @see ./docs/marksman_config.md */
+import { existsSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const MARKSMAN_BASELINE_PATH = join(HERE, 'data', 'marksman_config', 'marksman.baseline.toml')
+export const MARKSMAN_TARGET_FILENAME = '.marksman.toml'
+
+/**
+ * Перевіряє наявність `.marksman.toml` у корені; сигналить копіювання canonical baseline.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту (cwd, репортер).
+ * @returns {import('../../../scripts/lib/lint-surface/types.mjs').LintResult} результат перевірки з pass/fail.
+ */
+export function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+
+  if (!existsSync(MARKSMAN_BASELINE_PATH)) {
+    reporter.fail(`canonical baseline не знайдено (${MARKSMAN_BASELINE_PATH}) — перевстанови @7n/rules`)
+    return reporter.result()
+  }
+
+  const target = join(cwd, MARKSMAN_TARGET_FILENAME)
+  if (existsSync(target)) {
+    reporter.pass(`${MARKSMAN_TARGET_FILENAME} існує (${relative(cwd, target)})`)
+    return reporter.result()
+  }
+
+  reporter.fail(`${MARKSMAN_TARGET_FILENAME} відсутній — T0 скопіює canonical baseline (ci4.mdc)`, {
+    reason: 'marksman-config-missing',
+    file: MARKSMAN_TARGET_FILENAME,
+    data: { kind: 'marksman-config-missing' }
+  })
+  return reporter.result()
+}

package/rules/ci4/marksman_config/marksman_config.mdc

@@ -0,0 +1,31 @@
+## Конфіг marksman LSP (`.marksman.toml`)
+
+Правило перевіряє наявність `.marksman.toml` у корені проєкту. Якщо файл відсутній — автоматично створює його з canonical baseline, що постачається разом із пакетом (`js/data/marksman_config/marksman.baseline.toml`). Повторні прогони ідемпотентні: існуючий файл не перетирається, ручні правки зберігаються.
+
+### Baseline-конфіг
+
+Canonical baseline ([data/marksman_config/marksman.baseline.toml](./data/marksman_config/marksman.baseline.toml)) містить такі налаштування:
+
+```toml
+[core]
+markdown.file_extensions = ["md", "markdown"]
+markdown.glfm = true          # GitHub-Flavored Markdown (таблиці, todo, alerts)
+
+[completion]
+wiki.style = "file-stem"      # [[oidc-pkce-flow]] → docs/adr/oidc-pkce-flow.md
+
+[code_action]
+toc.enable = true             # «Insert/Update TOC» для довгих arc42-сторінок
+```
+
+**Чому `file-stem`?** ADR-slug збігається з іменем файлу — стабільний ідентифікатор у AUTOGEN `sources`, `manifest.json` і валідаторі. Якщо заголовок ADR змінюється, посилання `[[wiki-link]]` не ламається. Без явного конфіга marksman використовує `title-slug-ref` і вимкнений GLFM — частина задокументованої навігації працювала б інакше.
+
+### Поведінка перевірки
+
+| Стан                          | Результат                                          |
+| ----------------------------- | -------------------------------------------------- |
+| baseline-файл пакета відсутній | `fail` — перевстанови `@7n/rules`              |
+| `.marksman.toml` вже існує    | `pass` — файл не чіпається                        |
+| `.marksman.toml` відсутній    | створює файл з baseline, `pass`                    |
+
+Перевірка запускається як `check`-поверхня; `lint`-поверхні правило не має.

package/rules/ci4/vscode_extensions/concern.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".vscode/extensions.json"
+    }
+  }
+}

package/rules/ci4/vscode_extensions/docs/fix-vscode_extensions.md

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: fix-vscode_extensions.mjs
+resource: npm/rules/ci4/vscode_extensions/fix-vscode_extensions.mjs
+docgen:
+  crc: 3353fe17
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: best-of-2:retry-won,judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл відповідає за ініціалізацію процесу корекції розширень VS Code. Він виконує корекцію, використовуючи визначені у `../../../scripts/lib/fix/vscode-ext-add.mjs` шаблони.
+
+## Поведінка
+
+1. Ініціалізує логіку для корекції VS Code розширень.
+2. Використовує шаблони, визначені у `../../../scripts/lib/fix/vscode-ext-add.mjs`, для виконання корекції.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).