@nitra/cursor 1.13.12 → 1.13.13

package/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.13] - 2026-05-17
+
+### Added
+
+- `text` rule: до ланцюжка `lint-text` додано крок `dotenv-linter` (`runDotenvLinter()` у `npm/rules/text/lint/run-dotenv-linter.mjs`). На знайдених `.env*` рекурсивно по проєкту виконується `dotenv-linter fix -r --no-backup --quiet . --exclude node_modules --exclude .envrc`, після чого симетричний `check` для фінальної перевірки. Якщо інструмент відсутній у `PATH` — друкуються підказки встановлення (`brew install dotenv-linter` для macOS).
+- `text.mdc` (canonical + `.cursor/rules/n-text.mdc` mirror) описує новий крок і вимоги до `dotenv-linter` (тільки в `PATH`, **не** у `dependencies`/`devDependencies`).
+- `.cspell.json` — додано слово `envrc` (направлення на direnv-файл, не key=value).
+- Тест `npm/rules/text/lint/run-dotenv-linter.test.mjs` — порожнє дерево, авто-фікс `LowercaseKey`, ігнор `node_modules`/`.envrc`.
+
 ## [1.13.12] - 2026-05-17
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.13.12",
+  "version": "1.13.13",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/ci4/ci4.mdc

@@ -1,103 +1,332 @@
 ---
-description: Дизайн проєкту за C4 model (https://c4model.com); Markdown — джерело істини про архітектуру, рішення, тести й документацію
+description: Архітектурна документація продукту — Markdown як джерело істини; рекомендований стек arc42 + Diátaxis + ADR (MADR v4, формат описаний у правилі `adr`) + C4 як набір нотацій; гібридна модель manual + autogen-зон, що регенеруються з accepted ADR; MkDocs Material як viewer з collapsible engineer-блоками для змішаної аудиторії
 alwaysApply: true
-version: '1.0'
+version: '2.0'
 ---
 
-C4-діаграми проєкту живуть у Markdown поряд із кодом. Це не довідник «для людей із порталу
-архітектора» — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед
-будь-якою зміною коду. Тому правила нижче — не оформлення, а робочий процес.
+Архітектурна документація проєкту живе у Markdown поряд із кодом. Це не довідник «для людей із порталу архітектора» — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед будь-якою зміною коду. Тому правила нижче — не оформлення, а робочий процес: який стек використовуємо, як зберігаємо рішення, як автоматично перегенеровуємо проекції з ADR і як рендеримо для змішаної аудиторії (менеджери + інженери + ops).
+
+Формат самих ADR-файлів — MADR v4.0.0 minimal — описаний у правилі **`adr`** (`npm/rules/adr/adr.mdc`). Тут описано, як ADR використовуються як вхід для архітектурних проекцій, а не як вони створюються.
 
 ## Markdown як джерело істини
 
-Уся ключова інформація про проєкт — архітектура (C4), рішення (ADR), тести й документація —
-зберігається у `.md`/`.mdc`-файлах і є **офіційним джерелом істини**. Це єдиний спосіб
-тримати знання разом із кодом — версійно, в одному PR і доступно для агентів. Якщо щось
-важливе про систему існує лише у Confluence/Notion/месенджері — для проєкту цього **немає**.
+Уся ключова інформація про проєкт — архітектура, рішення (ADR), тести й документація — зберігається у `.md`/`.mdc`-файлах і є **офіційним джерелом істини**. Це єдиний спосіб тримати знання разом із кодом — версійно, в одному PR і доступно для агентів. Якщо щось важливе про систему існує лише у Confluence/Notion/месенджері — для проєкту цього **немає**.
 
 ## Специфікація як джерело істини (Spec-as-Source)
 
-У AI-native розробці первинним артефактом, який підтримують інженери, є **специфікація**, а не
-кодова база. Код — похідний артефакт, «будівельне риштування», яке агент генерує, верифікує або
-повністю відновлює зі специфікації. Якщо поведінка системи має змінитися — **спочатку оновлюємо
-специфікацію (C4/ADR/опис компонента), і лише потім** агент генерує відповідний код. Зворотний
-порядок («код вже написаний, доку напишемо потім») перетворює специфікацію на декорацію.
+У AI-native розробці первинним артефактом, який підтримують інженери, є **специфікація**, а не кодова база. Код — похідний артефакт, «будівельне риштування», яке агент генерує, верифікує або повністю відновлює зі специфікації. Якщо поведінка системи має змінитися — **спочатку оновлюємо специфікацію (arc42-розділ, ADR, опис компонента), і лише потім** агент генерує відповідний код. Зворотний порядок («код вже написаний, доку напишемо потім») перетворює специфікацію на декорацію.
 
 ## Тест на повне відтворення (Rebuild Test)
 
-Документація вважається повною лише тоді, коли проходить бінарний тест: якщо видалити теку
-`src/`, відкрити нову LLM-сесію з чистим контекстом і дати агенту доступ лише до `.md`-файлів —
-агент має **відтворити робочу кодову базу**. Архітектурні збої (агент не знає структуру тек),
-інтеграційні (неописані міжсервісні контракти), падіння юніт-тестів (неописана бізнес-логіка) —
-це не «складність задачі», а **прогалини документації**, які треба заповнити у тому ж PR.
+Документація вважається повною лише тоді, коли проходить бінарний тест: якщо видалити теку `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`.
+Вікно контексту 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`». Коли агент отримає лише цей фрагмент,
-у нього має бути повний словник для коректної генерації.
+RAG витягує **фрагменти**, не цілі документи. Тому кожен розділ має сенс **без сусіднього тексту**. Заборонено: «як було згадано вище», «ця змінна», «попередній метод», «той самий сервіс». Замість цього — щоразу явно повторюємо назву сутності: «автентифікація OAuth 2.0», «функція `calculateTotal()`», «контейнер `api-gateway`». Коли агент отримає лише цей фрагмент, у нього має бути повний словник для коректної генерації.
 
 ## Docs-as-Code
 
-Документація живе у Git поруч із кодом, проходить **той самий Code Review**, версіонується і
-автоматично перевіряється у CI (лінтери Markdown, валідатори посилань, `npx @nitra/cursor
-check`). Биті посилання й документація, що «не компілюється», — **блокуючий баг**, не
-косметика. Це продовження принципу «оновлення синхронно зі змінами» нижче: один PR — код +
-схема + ADR + тести.
+Документація живе у Git поруч із кодом, проходить **той самий Code Review**, версіонується і автоматично перевіряється у CI (лінтери Markdown, валідатори посилань, `npx @nitra/cursor check`). Биті посилання й документація, що «не компілюється», — **блокуючий баг**, не косметика.
 
 ## Трасування як документація недетермінованої поведінки
 
-Для компонентів, де рішення приймає нейромережа або складна евристика, класичної форми
-«вхід X → вихід Y» **недостатньо** — поведінка недетермінована. Джерелом істини стає
-**пайплайн логування й трасування**: які інструменти використав агент, який контекст мав,
-чому ухвалив це рішення. У C4-компоненті такого типу — посилання на дашборд/storage трасувань
-обов'язкове нарівні з посиланнями на тести.
+Для компонентів, де рішення приймає нейромережа або складна евристика, класичної форми «вхід 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`, ховається під `??? engineer`.
+- **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)
+│   ├── YYYYMMDD-HHMMSS-<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 (`YYYYMMDD-HHMMSS-*.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`** — apended-секції у тому ж файлі. Враховуються як еволюція рішення в хронологічному порядку.
+
+**Маршрутизація 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, не рендеряться у MkDocs):
+
+```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 — генератор зупиняється і вимагає рішення людини.
 
-## Розташування
+## Цикл оновлення
 
-C4-діаграми проєкту живуть у теці `docs/ci4/` — це **канонічне місце** для всіх рівнів
-моделі: `01-context.md`, `02-containers.md`, `03-components.md`, `04-code.md`, плюс
-супутні `README.md` (вступ) і `decisions.md` (зведення ADR-впливів на C4). Інших місць
-для C4-схем у репозиторії немає: розпорошення по підтеках сервісів ламає навігацію
-«від системи вглиб» і робить агентський аналіз перед зміною дорожчим.
+```
+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).
+
+## MkDocs Material: collapsible engineer-блоки
+
+Менеджер читає прозу зверху, інженер клікає `??? engineer` і провалюється глибше. Один документ — дві аудиторії без дублювання.
+
+`mkdocs.yml`:
+
+```yaml
+theme:
+  name: material
+  features:
+    - content.code.copy
+    - navigation.tabs
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed: { alternate_style: true }
+  - attr_list
+
+extra_css:
+  - stylesheets/audience.css
+```
+
+Синтаксис у документах:
+
+```markdown
+User Service автентифікує користувачів і керує профілями.
+Підтримуємо OIDC-логін та email/password.
+
+??? engineer "Технічна реалізація автентифікації"
+    OIDC-сервер на Fastify з PKCE flow [oidc-pkce-flow].
+    Refresh-токени з rotation, TTL 30 днів, Redis storage.
+
+Профілі зберігаються в основній БД, кешуються в Redis на 5 хв.
+
+??? ops "Деталі кешу та інвалідації"
+    Cache key: `user:profile:{userId}:v2`.
+    Інвалідація — NATS подія `user.profile.updated` [user-profile-events].
+```
+
+`???` = згорнуто за замовчуванням, `???+` = розгорнуто.
+
+Кастомні audience-styles у `docs/stylesheets/audience.css`:
+
+```css
+.md-typeset details.engineer > summary {
+  background-color: rgba(84, 110, 122, 0.1);
+  border-color: #546e7a;
+}
+.md-typeset details.ops > summary {
+  background-color: rgba(255, 152, 0, 0.1);
+  border-color: #ff9800;
+}
+```
+
+## Промпт для LLM-проекцій
+
+Тримати у `docs/.docgen/prompts/projection.md` як артефакт першого класу — версіонується, ревʼюється, тестується на golden-наборі ADR. Скелет:
+
+```
+Ти пишеш документацію для змішаної аудиторії (менеджери + інженери).
+
+Структура кожної секції:
+1. 2-4 речення прози рівня менеджера: що це робить, яку цінність дає,
+   як пов'язано з іншими частинами продукту. Без технологій, версій, коду.
+
+2. Технічні деталі — тільки всередині блоків:
+   ??? engineer "Описова назва блоку"
+       Код, конфіги, версії, посилання на ADR.
+
+3. Operational деталі:
+   ??? ops "Що моніторити та як реагувати"
+
+Правила:
+- Якщо прибрати всі ??? блоки, текст лишається зв'язним менеджерським документом.
+- Кожен факт з ADR маркуй [<slug>] всередині engineer-блоку — slug це ім'я clean ADR
+  без розширення (наприклад `[ланцюжок-запуску-abie]`).
+- Назви блоків — описові («Чому Percona, а не MariaDB»).
+- НЕ виходь за межі <!-- AUTOGEN:start --> ... <!-- AUTOGEN:end -->.
+- ADR без рядка `**Status:** Accepted` ігноруй.
+- Якщо в ADR є `## Update YYYY-MM-DD` секції — враховуй найсвіжіший стан рішення,
+  старі формулювання вважай застарілими.
+```
+
+## Типові поломки 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` відповідає фактичному контенту зон
+- Жоден `??? engineer` блок не з'являється в manager-only проекціях
+- Якщо в зоні згадано компонент — він є в `docs/glossary.md`
+- ADR без `**Status:** Accepted` не потрапили у проекцію
+
+Без валідатора накопичується тихий дрейф: посилання гниють, hash розходиться з контентом, термінологія дрейфує.
 
 ## Аналіз перед зміною
 
-Перш ніж вносити зміни, агент **читає відповідні C4-файли**: контекст, контейнери, компоненти
-тієї ділянки, до якої входить редагований код. Без цього кроку легко зламати приховані
-залежності між контейнерами або «загубити» зовнішню інтеграцію.
+Перш ніж вносити зміни в код, агент **читає відповідні docs**: контекст, контейнери, компоненти тієї ділянки, до якої входить редагований код, плюс accepted ADR за тематикою області (`docs/adr/<slug>.md` зі `**Status:** Accepted`). Без цього кроку легко зламати приховані залежності між сервісами або «загубити» зовнішню інтеграцію, описану в `explanation/architecture.md`.
 
 ## Оновлення синхронно зі змінами
 
-Кожна зміна, що впливає на C4-модель — нова інтеграція, новий компонент, перейменування,
-зміна напрямку залежності, видалення сервісу — **супроводжується оновленням C4-схеми у тому ж
-PR**. C4 не оновлюється «потім» окремою задачею: розсинхрон між кодом і моделлю — найчастіша
-причина, чому архітектурні документи перестають читати.
+Кожна зміна, що впливає на архітектуру — нова інтеграція, новий компонент, перейменування, зміна напрямку залежності, видалення сервісу — **супроводжується новим ADR (або `## Update YYYY-MM-DD` у наявному) і регенерацією проекцій у тому ж PR**. Документація не оновлюється «потім» окремою задачею: розсинхрон між кодом і моделлю — найчастіша причина, чому архітектурні документи перестають читати. Capture/normalize flow з правила `adr` забезпечує саму появу ADR — регенерацію проекцій ініціює окремий hook (наприклад, post-merge або `/regen-docs`).
 
 ## Зв'язок із ADR
 
-ADR (`docs/adr/`) описує **вплив рішення на C4**: які контейнери/компоненти з'являються,
-зникають, змінюють відповідальність. Якщо рішення суттєве — у тілі ADR явно пишемо, які
-C4-схеми потрібно оновити, і робимо це у тому ж PR.
+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 лишався читабельним як автономний документ.
 
 ## Зв'язок із тестами
 
-Кожен C4-компонент має **посилання на відповідні тести** — інтеграційні, e2e або юніт залежно
-від рівня. Так перехід «компонент → як його перевіряємо» займає один клік, а не пошук по
-репозиторію.
+Кожен опис компонента в `explanation/components/<name>.md` має **посилання на відповідні тести** — інтеграційні, e2e або юніт залежно від рівня. Так перехід «компонент → як його перевіряємо» займає один клік, а не пошук по репозиторію. Для агентських компонентів додаткове посилання на storage трасувань — нарівні з тестами, бо без них недетермінована поведінка непідтверджена.
 
 ## Зв'язок із документацією
 
-C4-схеми — частина **користувацької документації**, а не закритий артефакт для команди.
-Контекстна діаграма (рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у
-проєкт, а не у відокремленій теці «for-architects».
+Архітектурні артефакти — частина **користувацької документації**, а не закритий артефакт для команди. Контекстна діаграма (C4 рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у проєкт — у `explanation/architecture.md`, не у відокремленій теці «for-architects». MkDocs Material рендерить це з collapsible-блоками, тому менеджер бачить прозу, інженер провалюється в деталі.
+
+## Інструменти
+
+- **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:**`
+- **MkDocs + Material** як viewer
+- **Mermaid** для C4-діаграм, EventModeling, Context Maps у проекціях
+
+## Query mode як бонус
+
+Поверх проекцій — інтерактивний RAG над clean ADR. Інженер питає: «чому ми обрали Percona замість MariaDB?». LLM шукає по semantic index `Context and Problem Statement + Decision Outcome`, повертає `docs/adr/<slug>.md` з прямою цитатою. Корпус малий (десятки-сотні clean ADR після normalize) і структурований (фіксовані MADR-заголовки) — дешево й точно, без галюцинацій.

package/rules/text/lint/lint.mjs

@@ -2,18 +2,20 @@
  * CLI-обгортка над канонічним `lint-text` (text.mdc): послідовно
  *   1) `cspell .` — перевірка правопису з `@nitra/cspell-dict`;
  *   2) `runShellcheckText()` — авто-фікс і фінальна перевірка `*.sh` через `shellcheck`;
- *   3) `bunx markdownlint-cli2 --fix "**\/*.md" "**\/*.mdc"` — авто-фікс Markdown;
- *   4) `runV8rWithGlobs()` — schema-валідація json/json5/yaml/yml/toml через v8r з каталогом `@nitra/cursor`.
+ *   3) `runDotenvLinter()` — авто-фікс і фінальна перевірка `.env*` через `dotenv-linter`;
+ *   4) `bunx markdownlint-cli2 --fix "**\/*.md" "**\/*.mdc"` — авто-фікс Markdown;
+ *   5) `runV8rWithGlobs()` — schema-валідація json/json5/yaml/yml/toml через v8r з каталогом `@nitra/cursor`.
  *
  * Перший ненульовий код з ланцюжка повертається як код виходу; наступні кроки не запускаються.
  * Експортовано як `runLintTextCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-text`.
  */
 import { runLintStep } from '../../../scripts/utils/run-lint-step.mjs'
+import { runDotenvLinter } from './run-dotenv-linter.mjs'
 import { runShellcheckText } from './run-shellcheck.mjs'
 import { runV8rWithGlobs } from './run-v8r.mjs'
 
 /**
- * Виконує канонічний `lint-text`: cspell → run-shellcheck → markdownlint-cli2 → run-v8r.
+ * Виконує канонічний `lint-text`: cspell → run-shellcheck → run-dotenv-linter → markdownlint-cli2 → run-v8r.
  * Першу помилку повертаємо як код виходу; наступні кроки не запускаються.
  * Усі кроки синхронні (`spawnSync` + sync-ентрі з пакета), тому функція не async.
  * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
@@ -26,6 +28,10 @@ export function runLintTextCli() {
   const shellcheckCode = runShellcheckText()
   if (shellcheckCode !== 0) return shellcheckCode
 
+  console.log('\n▶ dotenv-linter (авто-фікс + фінальна перевірка .env*)')
+  const dotenvCode = runDotenvLinter()
+  if (dotenvCode !== 0) return dotenvCode
+
   const markdownlintCode = runLintStep('markdownlint', 'bunx', ['markdownlint-cli2', '--fix', '**/*.md', '**/*.mdc'])
   if (markdownlintCode !== 0) return markdownlintCode
 

package/rules/text/lint/run-dotenv-linter.mjs

@@ -0,0 +1,95 @@
+/**
+ * Запуск dotenv-linter у ланцюжку lint-text: спочатку авто-фікс, потім фінальна перевірка.
+ *
+ * dotenv-linter — швидкий лінтер для `.env`-файлів (LowercaseKey, DuplicatedKey, IncorrectDelimiter,
+ * UnorderedKey тощо). Інструмент очікується у PATH і **не** додається в `dependencies`/`devDependencies`
+ * (аналогічно shellcheck). Якщо `dotenv-linter` відсутній — друкуємо підказки встановлення
+ * (`brew install dotenv-linter` на macOS) і повертаємо 1.
+ *
+ * Файли шукає сам `dotenv-linter` у режимі `-r` (рекурсивно по дереву проєкту). Виключаємо
+ * `node_modules` і `.envrc` (direnv shell-синтаксис, не key=value формат). `.bak`-файли інструмент
+ * ігнорує самостійно. Якщо `.env*`-файлів немає, dotenv-linter повертає 0 ("Nothing to check").
+ *
+ * Авто-фікс — один прогон `dotenv-linter fix -r --no-backup --quiet . --exclude …` (інструмент сам
+ * застосовує усі виправлення без потреби в diff/patch, на відміну від shellcheck). Після цього —
+ * фінальний `dotenv-linter check -r --quiet . --exclude …`; будь-яке залишкове порушення — ненульовий
+ * код виходу.
+ */
+import { spawnSync } from 'node:child_process'
+import { resolve } from 'node:path'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+
+/** Каталоги/файли, які виключаємо з рекурсивного сканування dotenv-linter. */
+const EXCLUDED_PATHS = ['node_modules', '.envrc']
+
+/**
+ * Друкує підказки встановлення dotenv-linter у stderr.
+ * @returns {void}
+ */
+function printDotenvLinterInstallHints() {
+  process.stderr.write(
+    [
+      '❌ dotenv-linter не знайдено в PATH.',
+      'Встанови інструмент і повтори lint-text:',
+      '  macOS:    brew install dotenv-linter',
+      '  Linux:    curl -sSfL https://git.io/JLbXn | sh -s -- -b /usr/local/bin',
+      '  cargo:    cargo install dotenv-linter',
+      ''
+    ].join('\n')
+  )
+}
+
+/**
+ * Будує перелік аргументів `--exclude <path>` для dotenv-linter.
+ * @returns {string[]} плоский масив `['--exclude', 'node_modules', '--exclude', '.envrc']`
+ */
+function buildExcludeArgs() {
+  return EXCLUDED_PATHS.flatMap(p => ['--exclude', p])
+}
+
+/**
+ * Запускає dotenv-linter з авто-фіксом і фінальною перевіркою.
+ * @param {string} [cwd] робочий каталог (за замовчуванням `process.cwd()`)
+ * @returns {number} 0 — OK; 1 — інструмент відсутній або є залишкові порушення
+ */
+export function runDotenvLinter(cwd = process.cwd()) {
+  const root = resolve(cwd)
+  const bin = resolveCmd('dotenv-linter')
+  if (!bin) {
+    printDotenvLinterInstallHints()
+    return 1
+  }
+
+  const exclude = buildExcludeArgs()
+  const fixRun = spawnSync(bin, ['fix', '-r', '--no-backup', '--quiet', ...exclude, '.'], {
+    cwd: root,
+    encoding: 'utf8',
+    env: process.env,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+  if (fixRun.error) {
+    process.stderr.write(`${fixRun.error.message}\n`)
+    return 1
+  }
+
+  const checkRun = spawnSync(bin, ['check', '-r', '--quiet', ...exclude, '.'], {
+    cwd: root,
+    encoding: 'utf8',
+    env: process.env,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+  if (checkRun.error) {
+    process.stderr.write(`${checkRun.error.message}\n`)
+    return 1
+  }
+  if (checkRun.status === 0) return 0
+  if (checkRun.stdout?.length) process.stdout.write(checkRun.stdout)
+  if (checkRun.stderr?.length) process.stderr.write(checkRun.stderr)
+  return 1
+}
+
+if (isRunAsCli()) {
+  process.exitCode = runDotenvLinter()
+}

package/rules/text/text.mdc

@@ -1,10 +1,10 @@
 ---
-description: Обробка та перевірка текстових файлів, oxfmt, cspell, shellcheck (sh), markdownlint-cli2, v8r, CI
+description: Обробка та перевірка текстових файлів, oxfmt, cspell, shellcheck (sh), dotenv-linter (.env*), markdownlint-cli2, v8r, CI
 alwaysApply: true
-version: '1.26'
+version: '1.27'
 ---
 
-**oxfmt** (`.oxfmtrc.json`, редактор), **cspell**, **shellcheck** (tracked `*.sh` у `lint-text`), **markdownlint-cli2**, **[v8r](https://chris48s.github.io/v8r/)** ([Schema Store](https://www.schemastore.org/)), розширення **DavidAnson.vscode-markdownlint** / **timonwong.shellcheck**, workflow **`lint-text`**.
+**oxfmt** (`.oxfmtrc.json`, редактор), **cspell**, **shellcheck** (tracked `*.sh` у `lint-text`), **[dotenv-linter](https://dotenv-linter.github.io/)** (`.env*` у `lint-text`), **markdownlint-cli2**, **[v8r](https://chris48s.github.io/v8r/)** ([Schema Store](https://www.schemastore.org/)), розширення **DavidAnson.vscode-markdownlint** / **timonwong.shellcheck**, workflow **`lint-text`**.
 
 ```json title=".vscode/extensions.json"
 {
@@ -115,6 +115,8 @@ version: '1.26'
 
 **shellcheck:** інструмент лише в **`PATH`** (як у **ga.mdc** для `lint-ga`), **не** додавай до `dependencies` / `devDependencies`. Якщо `shellcheck` відсутній — встанови локально (**macOS:** `brew install shellcheck`; **Debian/Ubuntu:** `sudo apt-get install -y shellcheck`; **Arch:** `sudo pacman -S shellcheck`). Канонічний **`lint-text`** делегує до CLI **`n-cursor lint-text`** (бінарка з `node_modules/.bin/` пакету `@nitra/cursor`): після **`cspell .`** виконується **`runShellcheckText()`** з пакета — циклічно **`shellcheck -f diff`** і **`patch -p1`** для авто-виправлень, потім повний прогін **`shellcheck`** по всіх tracked `*.sh` (у git) або по `**/*.sh` без `node_modules`. Потрібен також **`patch`** у `PATH` (на macOS зазвичай уже є).
 
+**dotenv-linter:** після shellcheck CLI запускає **`runDotenvLinter()`** з пакета — рекурсивно по `.env*`-файлах проєкту через **`dotenv-linter fix -r --no-backup --quiet . --exclude node_modules --exclude .envrc`**, далі такий самий **`check`** для фінальної перевірки. Інструмент має бути в **`PATH`** і **не** додається в `dependencies` / `devDependencies`. Якщо `dotenv-linter` відсутній — встанови локально (**macOS:** `brew install dotenv-linter`; **Linux:** `curl -sSfL https://git.io/JLbXn | sh -s -- -b /usr/local/bin`; через **cargo:** `cargo install dotenv-linter`).
+
 У v8r **немає** прапорця тихого режиму; CLI-обгортка **`n-cursor lint-text`** на четвертому кроці викликає **`runV8rWithGlobs()`** з пакета (реалізація — `npm/rules/text/js/run-v8r.mjs`): під капотом послідовні **`bunx v8r`** для кожного типу (**json**, **json5**, **yml**, **yaml**, **toml**), бо один процес v8r з кількома глобами падає з **98**, якщо хоч один glob порожній, і тоді інші розширення не перевіряються. Вивід при кодах **0** і **98** не показується. Каталог схем **`schemas/v8r-catalog.json`** пакета `@nitra/cursor` обгортка підставляє в v8r сама.
 
 ```json title="package.json"

package/skills/abie-clean/SKILL.md

@@ -9,12 +9,16 @@ version: '1.1'
 
 Скіл прибирає з проєкту все, що належить **ru-середовищу**. Залишаються тільки `dev` (як база) та `ua` як активне продакшн-середовище. Працюй послідовно по секціях нижче — після кожної секції перевіряй, що проєкт лишається консистентним (`kustomization.yaml` посилається лише на наявні файли, GitHub Actions-вирази синтаксично коректні).
 
+## 0. Що НЕ чіпати
+
+**`node_modules/`** (і будь-які `**/node_modules/`) — повністю виключаються з аналізу й модифікацій. Це згенеровані залежності: збіги на `ru`, `values-ru.*`, `cr.yandex` тощо там нерелевантні і відновляться при наступному `install`. Усі `find` / `git grep` / автозаміни мають пропускати ці шляхи. Аналогічно не чіпай `.git/`, `dist/`, `build/`, `.next/`, `.nuxt/`, `.output/`, `coverage/`.
+
 ## 1. Директорії з назвою `ru`
 
-Видали всі директорії з назвою `ru` у проєкті:
+Видали всі директорії з назвою `ru` у проєкті (крім тих, що всередині `node_modules`):
 
 ```bash
-find . -type d -name "ru" -exec rm -rf {} +
+find . -type d \( -name node_modules -o -name .git \) -prune -o -type d -name "ru" -print -exec rm -rf {} +
 ```
 
 Це чистить як `country/ru/`, так і `k8s/<...>/ru/` (overlay у kustomize). Після видалення overlay `ru/` обов’язково прибери відповідний запис у `resources:` у батьківському `kustomization.yaml`, якщо він там лишився.
@@ -27,7 +31,8 @@ find . -type d -name "ru" -exec rm -rf {} +
 - будь-які файли, що закінчуються на `-ru` або `-ru.<ext>`, наприклад `site/.env.prod-ru`, `*.env.prod-ru`, `*.prod-ru.conf`
 
 ```bash
-find . -type f \( -name "values-ru.*" -o -name "*-ru" -o -name "*.prod-ru" -o -name "*.prod-ru.*" \) -delete
+find . -type d \( -name node_modules -o -name .git \) -prune -o \
+  -type f \( -name "values-ru.*" -o -name "*-ru" -o -name "*.prod-ru" -o -name "*.prod-ru.*" \) -print -delete
 ```
 
 ## 3. `.github/workflows/*.yml`
@@ -194,5 +199,5 @@ const tr = {
 ## 6. Після очистки
 
 - Переконайся, що `kustomization.yaml` у кожній директорії `k8s/` не посилається на видалені overlay або файли.
-- Пройдись `git grep` по репозиторію на залишки: `git grep -n -i -e '\bru\b' -e cr\.yandex -e country/ru -e prod-ru -e values-ru -e "'ya'"` — переглянь усі знахідки вручну, бо `ru` як слово може траплятися в легітимних контекстах (наприклад, `truncate`, `Aurum`, `cruft`). Видаляй лише ті входження, що належать ru-середовищу.
+- Пройдись `git grep` по репозиторію на залишки: `git grep -n -i -e '\bru\b' -e cr\.yandex -e country/ru -e prod-ru -e values-ru -e "'ya'"` — переглянь усі знахідки вручну, бо `ru` як слово може траплятися в легітимних контекстах (наприклад, `truncate`, `Aurum`, `cruft`). Видаляй лише ті входження, що належать ru-середовищу. `git grep` за замовчуванням пропускає невідстежувані шляхи, тож `node_modules/` у вихід не потрапить, поки воно у `.gitignore`.
 - Перевір CI локально: `npx @nitra/cursor check abie` (якщо правило **abie** ввімкнене у проєкті).