@7n/rules 1.0.0

package/rules/rego/tooling/concern.json

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

package/rules/rego/tooling/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/rego/tooling
+resource: npm/rules/rego/tooling/
+---
+
+# npm/rules/rego/tooling
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

package/rules/rego/tooling/docs/main.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/rego/tooling/main.mjs
+docgen:
+  crc: bc5fef0b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
+  issues: anchor-miss:(rego.mdc),judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл визначає, чи існує конфігураційний файл `.regal/config.yaml` у корені проєкту. Це дає змогу системі перевірити наявність необхідної конфігурації для правил, визначених у `rego.mdc`, та створити цей файл, якщо він відсутній.
+
+Викликаючи `main`, система перевіряє наявність файлу `.regal/config.yaml` у корені проєкту. Якщо файл існує, це підтверджує відповідність конфігурації вимогам `rego.mdc`, включаючи маркери повідомлень (згадай у Поведінці). Якщо файл відсутній, це вказує на необхідність створення `.regal/config.yaml` у корені проєкту для забезпечення роботи `rego.mdc` та відображення маркерів повідомлень.
+
+## Поведінка
+
+1. Викликаючи main, система перевіряє наявність файлу .regal/config.yaml у корені проєкту.
+2. Якщо файл існує, це засвідчує наявність конфігурації для rego.mdc.
+3. Якщо файл відсутній, це сигналізує про необхідність створити .regal/config.yaml у корені проєкту для rego.mdc.
+
+## Публічний API
+
+main — шукає конфігураційний файл `.regal/config.yaml` у корені проєкту.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/rego/tooling/main.mjs

@@ -0,0 +1,25 @@
+/** @see ./docs/tooling.md */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+/**
+ * Перевіряє наявність `.regal/config.yaml` у корені проєкту.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст lint-прогону (cwd тощо)
+ * @returns {import('../../../scripts/lib/lint-surface/types.mjs').LintResult} результат зі зібраними violations
+ */
+export function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+
+  const regalConfig = join(cwd, '.regal', 'config.yaml')
+  if (existsSync(regalConfig)) {
+    pass('.regal/config.yaml існує (rego.mdc)')
+  } else {
+    fail('.regal/config.yaml не існує — створи у корені проєкту (rego.mdc)')
+  }
+
+  return reporter.result()
+}

package/rules/rego/tooling/tooling.mdc

@@ -0,0 +1,14 @@
+## Rego tooling: `.regal/config.yaml`
+
+У корені проєкту **має бути** файл `.regal/config.yaml` — конфіг лінтера [regal](https://docs.styra.com/regal).
+
+Мінімальний приклад (вимикає `no-defined-entrypoint` для conftest-полісі):
+
+```yaml title=".regal/config.yaml"
+rules:
+  idiomatic:
+    no-defined-entrypoint:
+      level: ignore
+```
+
+`regal lint` запускається через `n-rules lint rego`; без `.regal/config.yaml` regal використовує дефолти і може помилково флагувати conftest `deny`-правила як entrypoint-порушення.

package/rules/rego/vscode_extensions/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".vscode/extensions.json",
+      "required": true
+    },
+    "missingMessage": ".vscode/extensions.json не існує — створи згідно rego.mdc (rego.vscode_extensions)"
+  }
+}

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

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

package/rules/rego/vscode_extensions/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/rego/vscode_extensions
+resource: npm/rules/rego/vscode_extensions/
+---
+
+# npm/rules/rego/vscode_extensions
+
+| Файл                                                  | Тип       |
+| ----------------------------------------------------- | --------- |
+| [fix-vscode_extensions.mjs](fix-vscode_extensions.md) | JS Module |

package/rules/rego/vscode_extensions/fix-vscode_extensions.mjs

@@ -0,0 +1 @@
+export { patterns } from '../../../scripts/lib/fix/vscode-ext-add.mjs'

package/rules/rego/vscode_extensions/template/extensions.json.snippet.json

@@ -0,0 +1 @@
+{ "recommendations": ["tsandall.opa"] }

package/rules/rego/vscode_extensions/vscode_extensions.mdc

@@ -0,0 +1,11 @@
+## Rego-перевірка наявності tsandall.opa у recommendations
+
+Rego-пакет: `rego.vscode_extensions`
+
+Цільовий файл: `.vscode/extensions.json`
+
+Перевіряє: поле `recommendations` містить рядок `"tsandall.opa"`. Порожній масив або відсутнє поле — deny. Додаткові записи дозволені.
+
+Канонічний сніпет: [extensions.json.snippet.json](./template/extensions.json.snippet.json)
+
+Логіка: subset-of — кожна рекомендація зі сніпету має бути присутня у `recommendations` вхідного файлу. Канон надходить через `--data` як `data.template.snippet`.

package/rules/rego/vscode_extensions/vscode_extensions.rego

@@ -0,0 +1,15 @@
+# Перевірка `.vscode/extensions.json` для rego (rego.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/extensions.json.snippet.json.
+# `recommendations` — subset-of: кожна рекомендація з template має бути у input.
+# Додаткові рекомендації від інших правил дозволені.
+package rego.vscode_extensions
+
+import rego.v1
+
+deny contains msg if {
+	some rec in data.template.snippet.recommendations
+	not rec in {r | some r in object.get(input, "recommendations", [])}
+	msg := sprintf(".vscode/extensions.json: recommendations має містити %q (rego.mdc)", [rec])
+}

package/rules/rego/vscode_settings/concern.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".vscode/settings.json",
+      "required": true
+    },
+    "missingMessage": ".vscode/settings.json не існує — створи згідно rego.mdc (rego.vscode_settings)"
+  }
+}

package/rules/rego/vscode_settings/template/settings.json.snippet.json

@@ -0,0 +1,6 @@
+{
+  "[rego]": {
+    "editor.defaultFormatter": "tsandall.opa",
+    "editor.formatOnSave": true
+  }
+}

package/rules/rego/vscode_settings/vscode_settings.mdc

@@ -0,0 +1,19 @@
+## Rego-gate: налаштування форматера rego у `.vscode/settings.json`
+
+Rego-пакет: `rego.vscode_settings`
+
+Цільовий файл: `.vscode/settings.json`
+
+Перевіряє `[rego]`-блок — два листові ключі:
+
+- `editor.defaultFormatter` має дорівнювати `"tsandall.opa"`
+- `editor.formatOnSave` має бути `true`
+
+Канонічний сніпет: [settings.json.snippet.json](./template/settings.json.snippet.json)
+
+Два незалежні deny-правила:
+
+1. Leaf-by-leaf: якщо `[rego]`-блок є обʼєктом — кожне ключ/значення зі сніпету звіряється з фактичним значенням (відсутнє або відмінне — deny).
+2. Тип: якщо `[rego]`-блок присутній, але не є обʼєктом (наприклад, рядок) — окрема помилка типу.
+
+Канон надходить через `--data` як `data.template.snippet`.

package/rules/rego/vscode_settings/vscode_settings.rego

@@ -0,0 +1,30 @@
+# Перевірка `.vscode/settings.json` для rego (rego.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/settings.json.snippet.json.
+# Snippet — 2-рівнева мапа: <language-block-key>.<setting-key> = <expected>
+# (VS Code-конвенція: ключі `[rego]` і `editor.defaultFormatter`/`editor.formatOnSave`
+# — це літеральні string-keys із дужками/крапкою, не вкладені обʼєкти).
+package rego.vscode_settings
+
+import rego.v1
+
+# Leaf-by-leaf: працює коли block присутній і є обʼєктом.
+deny contains msg if {
+	some block_key, expected_inner in data.template.snippet
+	inner := object.get(input, block_key, {})
+	is_object(inner)
+	some leaf_key, expected_value in expected_inner
+	actual := object.get(inner, leaf_key, null)
+	actual != expected_value
+	msg := sprintf(".vscode/settings.json: %s.%s має бути %v (rego.mdc)", [block_key, leaf_key, expected_value])
+}
+
+# Block існує, але не обʼєкт (напр. рядок) — окрема помилка типу.
+deny contains msg if {
+	some block_key in object.keys(data.template.snippet)
+	raw := object.get(input, block_key, null)
+	raw != null
+	not is_object(raw)
+	msg := sprintf(".vscode/settings.json: %s має бути обʼєктом (rego.mdc)", [block_key])
+}

package/rules/release/change.mjs

@@ -0,0 +1,88 @@
+/**
+ * `n-rules change` — пише один change-файл `<ws>/.changes/YYMMDD-HHMM.md`.
+ * Якщо файл за ту саму хвилину вже існує, додає `-2`, `-3` тощо.
+ * Замінює ручне редагування CHANGELOG у feature-флоу (n-changelog.mdc v3.0).
+ */
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { CHANGES_DIR, changeFileName, parseChangeFile, serializeChangeFile } from './lib/change-file.mjs'
+
+/**
+ * @param {unknown} error помилка `writeFile`
+ * @returns {boolean} true, якщо файл уже існує
+ */
+function isFileExistsError(error) {
+  return error instanceof Error && 'code' in error && error.code === 'EEXIST'
+}
+
+/**
+ * Записує change-файл create-only, додаючи числовий suffix лише при локальній колізії.
+ * @param {string} dir абсолютний шлях до `.changes`
+ * @param {string} content вміст change-файлу
+ * @param {number} timestamp epoch milliseconds
+ * @returns {Promise<string>} створене ім'я файла
+ */
+async function writeUniqueChangeFile(dir, content, timestamp) {
+  for (let sequence = 1; ; sequence++) {
+    const name = changeFileName(timestamp, sequence)
+    try {
+      await writeFile(join(dir, name), content, { flag: 'wx' })
+      return name
+    } catch (error) {
+      if (isFileExistsError(error)) continue
+      throw error
+    }
+  }
+}
+
+/**
+ * @param {object} params параметри
+ * @param {string} params.bump `major|minor|patch`
+ * @param {string} params.section `Added|Changed|Fixed|Removed`
+ * @param {string} params.message опис
+ * @param {string} [params.ws] workspace (за замовчуванням `.`)
+ * @param {string} [params.cwd] корінь
+ * @param {number} [params.timestamp] epoch milliseconds для детермінованих тестів
+ * @returns {Promise<string>} відносний шлях створеного файлу (від ws)
+ */
+export async function writeChange({ bump, section, message, ws = '.', cwd = process.cwd(), timestamp = Date.now() }) {
+  const description = (message ?? '').trim()
+  const content = serializeChangeFile({ bump, section, description })
+  // Валідація полів: parseChangeFile кидає зрозумілу помилку на невалідних bump/section/порожньому описі.
+  parseChangeFile(content)
+
+  const dir = join(cwd, ws, CHANGES_DIR)
+  await mkdir(dir, { recursive: true })
+  const name = await writeUniqueChangeFile(dir, content, timestamp)
+  return join(CHANGES_DIR, name)
+}
+
+/**
+ * @param {string[]} args аргументи CLI (`--bump`, `--section`, `--message`, `--ws`)
+ * @returns {Promise<number>} exit-код
+ */
+export async function runChangeCli(args) {
+  const get = flag => {
+    const i = args.indexOf(flag)
+    return i !== -1 && i + 1 < args.length ? args[i + 1] : undefined
+  }
+  const bump = get('--bump')
+  const section = get('--section')
+  const message = get('--message')
+  if (!bump || !section || !message) {
+    console.error(
+      '❌ Використання: n-rules change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]'
+    )
+    return 1
+  }
+  const ws = get('--ws') ?? '.'
+  try {
+    const rel = await writeChange({ bump, section, message, ws })
+    console.log(`✅ ${join(ws, rel)}`)
+    return 0
+  } catch (error) {
+    console.error(`❌ ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}

package/rules/release/docs/change.md

@@ -0,0 +1,189 @@
+---
+type: JS Module
+title: change.mjs
+resource: npm/rules/release/change.mjs
+docgen:
+  crc: c119d596
+---
+
+Модуль реалізує CLI-команду `n-rules change`, яка створює **один** change-файл у каталозі `<ws>/.changes/<timestamp>-<rand>.md` усередині конкретного workspace монорепо. Файл містить мінімальний YAML-frontmatter (`bump`, `section`) та текст опису зміни.
+
+Призначення — замінити ручне редагування `CHANGELOG.md` під час feature-флоу: розробник (або агент) додає декларативний запис про зміну, а агрегація у фінальний `CHANGELOG.md` відбувається пізніше в CI (відповідно до правила `n-changelog.mdc` v3.0).
+
+Файл експонує дві функції:
+
+- `writeChange(...)` — програмний API для запису одного change-файлу;
+- `runChangeCli(args)` — обгортка для запуску з аргументів командного рядка.
+
+Серіалізація, парсинг, валідація та формування імені файлу делеговані сусідньому модулю `./lib/change-file.mjs`.
+
+## Експорти / API
+
+| Експорт        | Тип              | Призначення                                                                                                                 |
+| -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `writeChange`  | `async function` | Створює один change-файл у `<ws>/.changes/` та повертає його шлях відносно workspace.                                       |
+| `runChangeCli` | `async function` | Парсить CLI-аргументи (`--bump`, `--section`, `--message`, `--ws`), викликає `writeChange` і повертає exit-код для процесу. |
+
+Модуль не має експортованих констант чи класів, лише ці дві функції. `default`-експорт відсутній — використовуються лише іменовані експорти.
+
+## Функції
+
+### `writeChange({ bump, section, message, ws, cwd })`
+
+Програмний рівень: створює один change-файл і повертає його шлях, придатний для логування.
+
+**Сигнатура:**
+
+```js
+async function writeChange({
+  bump,           // string: 'major' | 'minor' | 'patch'
+  section,        // string: 'Added' | 'Changed' | 'Fixed' | 'Removed'
+  message,        // string: текст опису (буде обрізаний trim'ом)
+  ws = '.',       // string: відносний шлях workspace від cwd (за замовчуванням поточний)
+  cwd = process.cwd(), // string: корінь репозиторію
+}): Promise<string>
+```
+
+**Параметри:**
+
+- `bump` _(string, обов'язковий)_ — рівень semver-бампу. Дозволені значення: `major`, `minor`, `patch` (перевіряється у `parseChangeFile`).
+- `section` _(string, обов'язковий)_ — секція Keep a Changelog. Дозволені значення: `Added`, `Changed`, `Fixed`, `Removed`.
+- `message` _(string, обов'язковий)_ — людиночитаний опис зміни. Якщо `null/undefined`, перетворюється на порожній рядок; далі застосовується `trim()`. Порожній (після обрізки) опис призведе до помилки валідації.
+- `ws` _(string, необов'язковий, default `.`)_ — шлях workspace відносно `cwd`. Дозволяє писати change-файли в конкретний підпроект монорепо.
+- `cwd` _(string, необов'язковий, default `process.cwd()`)_ — корінь репозиторію. Винесений у параметр для тестованості.
+
+**Повертає:** `Promise<string>` — відносний шлях створеного файлу від кореня workspace (`ws`), у форматі `.changes/<timestamp>-<rand>.md`. Зауважте: шлях **не** включає сам `ws` — це робить його зручним для подальшого логування `join(ws, rel)`.
+
+**Side effects:**
+
+1. Серіалізує запис через `serializeChangeFile({ bump, section, description })`.
+2. **Валідує** серіалізований вміст через `parseChangeFile(content)` — це гарантує, що файл, який буде записаний, є валідним відповідно до тих самих правил, що використовуються при подальшому читанні. Невалідні `bump`/`section` чи порожній опис призведуть до `throw Error(...)` зі зрозумілим повідомленням українською.
+3. Створює каталог `<cwd>/<ws>/.changes/` (рекурсивно, `mkdir(..., { recursive: true })`) — не падає, якщо каталог уже існує.
+4. Генерує унікальне ім'я файлу через `newChangeFileName()` (timestamp + випадковий hex-суфікс, що захищає від колізій паралельних агентів у тій самій мілісекунді).
+5. Записує файл на диск (`writeFile`). Якщо файл випадково існує — буде перезаписаний (хоча колізія за іменем практично виключена через rand-суфікс).
+
+**Виняткові ситуації:**
+
+- Помилка валідації `parseChangeFile` (невалідні `bump`/`section`, порожній опис) — кидає `Error` із текстом помилки українською.
+- Помилки FS (наприклад, відсутність прав на створення каталогу) — кидаються як стандартні `Error` із Node.js.
+
+### `runChangeCli(args)`
+
+CLI-обгортка: розбирає аргументи, викликає `writeChange` і повертає exit-код. Не викликає `process.exit` — це робить виклична сторона (`bin`-скрипт).
+
+**Сигнатура:**
+
+```js
+async function runChangeCli(args: string[]): Promise<number>
+```
+
+**Параметри:**
+
+- `args` _(string[], обов'язковий)_ — масив аргументів CLI (зазвичай `process.argv.slice(2)`).
+
+**Розпізнавані прапори** (парсер мінімалістичний, не використовує бібліотеку):
+
+- `--bump <major|minor|patch>` — обов'язковий.
+- `--section <Added|Changed|Fixed|Removed>` — обов'язковий.
+- `--message "<опис>"` — обов'язковий.
+- `--ws <шлях>` — необов'язковий, default `.`.
+
+Кожен прапор шукається через `args.indexOf(flag)`; значення береться з наступного елемента (`args[i + 1]`). Якщо прапора немає, або він є останнім — значення `undefined`. Через таку реалізацію значення `--message`, що починається з тире (наприклад, `--message "--foo"`), розбереться коректно, але кілька прапорів з одним іменем не підтримуються (береться перше входження).
+
+**Повертає:** `Promise<number>` — exit-код:
+
+- `0` — успіх; у `stdout` пишеться `✅ <ws>/<rel>` (де `rel` — шлях, повернений `writeChange`).
+- `1` — помилка:
+  - Якщо бракує одного з обов'язкових прапорів (`--bump`, `--section`, `--message`) — у `stderr` пишеться рядок-підказка з повним usage-описом українською.
+  - Якщо `writeChange` кинув виняток — у `stderr` пишеться `❌ <message>` (для `Error` — `error.message`, для всього іншого — `String(error)`).
+
+**Side effects:**
+
+- Пише в `console.log` (`stdout`) на успіх.
+- Пише в `console.error` (`stderr`) на помилку.
+- Через `writeChange` — створює каталог і файл (див. вище).
+
+## Залежності
+
+### Зовнішні (Node.js core)
+
+- `node:fs/promises`:
+  - `mkdir` — рекурсивне створення `<ws>/.changes/`.
+  - `writeFile` — запис вмісту файлу.
+- `node:path`:
+  - `join` — побудова абсолютних і відносних шляхів (платформонезалежно).
+
+### Внутрішні (сусідній модуль `./lib/change-file.mjs`)
+
+- `CHANGES_DIR` _(string-константа `'.changes'`)_ — назва підкаталогу всередині workspace.
+- `newChangeFileName()` — генератор унікального імені файлу (`<Date.now()>-<3byte-hex>.md`).
+- `parseChangeFile(text)` — парсер + валідатор; використовується **тут** для валідації перед записом. Кидає `Error` зі зрозумілим текстом при невалідних `bump`, `section` або порожньому описі.
+- `serializeChangeFile({ bump, section, description })` — формує текст change-файлу: `---\nbump: ...\nsection: ...\n---\n<description>\n`.
+
+Валідні значення `bump` — `major|minor|patch`; валідні значення `section` — `Added|Changed|Fixed|Removed` (експортовані як `VALID_BUMPS` та `VALID_SECTIONS` у `change-file.mjs`).
+
+### Глобальні
+
+- `process.cwd()` — використовується як default для `cwd` у `writeChange`.
+- `console.log`, `console.error` — для CLI-виводу.
+
+## Потік виконання / Використання
+
+### Сценарій 1: програмний виклик `writeChange`
+
+```js
+import { writeChange } from './change.mjs'
+
+const rel = await writeChange({
+  bump: 'patch',
+  section: 'Fixed',
+  message: 'Fix off-by-one у валідаторі change-файлів',
+  ws: 'npm/rules/release'
+})
+// rel === '.changes/1735000000000-a1b2c3.md'
+```
+
+Послідовність кроків усередині:
+
+1. `description = (message ?? '').trim()`.
+2. `content = serializeChangeFile({ bump, section, description })` — формується текст із frontmatter.
+3. `parseChangeFile(content)` — перевіряє коректність (`bump`, `section`, непорожній опис); кидає `Error` за невалідних даних.
+4. `mkdir(join(cwd, ws, '.changes'), { recursive: true })` — створює каталог за потреби.
+5. `name = newChangeFileName()` — `Date.now() + 3-byte hex`.
+6. `writeFile(join(dir, name), content)` — атомарно записує файл.
+7. Повертає `join('.changes', name)` — шлях відносно `ws`.
+
+### Сценарій 2: запуск через CLI
+
+```bash
+n-rules change \
+  --bump patch \
+  --section Fixed \
+  --message "Fix off-by-one у валідаторі change-файлів" \
+  --ws npm/rules/release
+```
+
+Послідовність кроків усередині `runChangeCli`:
+
+1. Витягуються чотири значення через локальну функцію `get(flag)`.
+2. Якщо бракує `--bump`, `--section` або `--message` — друкується usage-рядок у `stderr`, повертається `1`.
+3. У `try/catch` викликається `writeChange({ bump, section, message, ws })`.
+4. На успіх — `console.log('✅ <ws>/<rel>')`, return `0`.
+5. На виняток — `console.error('❌ <message>')`, return `1`.
+
+### Інтеграція з feature-флоу
+
+Файл є частиною release-інфраструктури (`npm/rules/release/`). Створені цією командою change-файли пізніше зчитуються через `readChangeFiles(ws)` з `./lib/change-file.mjs` під час релізу, агрегуються та конвертуються в записи `CHANGELOG.md`. Це усуває конфлікти злиття в `CHANGELOG.md` при паралельних feature-гілках: кожен PR додає **новий** файл із унікальним іменем замість редагування спільного.
+
+### Анти-колізія паралельних агентів
+
+Унікальність імені файлу гарантується комбінацією:
+
+- `Date.now()` — мілісекундний timestamp (порядок створення зберігається лексикографічно).
+- `randomBytes(3).toString('hex')` — 6 шістнадцяткових символів випадковості (≈ 16M варіантів) у межах однієї мілісекунди.
+
+Це робить безпечним одночасний запис із різних worktree чи паралельних агентів `n-rules` без блокувань і без координації через FS.
+
+## Rebuild Test
+
+Документація відображає реальний стан файлу `change.mjs` (60 рядків, версія на момент створення документації): два іменовані експорти `writeChange` та `runChangeCli`, валідація через `parseChangeFile` після серіалізації, default `ws = '.'`, default `cwd = process.cwd()`, обов'язкові CLI-прапори `--bump`/`--section`/`--message`, опціональний `--ws`, exit-коди `0`/`1`, повідомлення українською з префіксами `✅`/`❌`. Залежності — `node:fs/promises` (`mkdir`, `writeFile`), `node:path` (`join`), `./lib/change-file.mjs` (`CHANGES_DIR`, `newChangeFileName`, `parseChangeFile`, `serializeChangeFile`).

package/rules/release/docs/index.md

@@ -0,0 +1,13 @@
+---
+type: Directory Index
+title: npm/rules/release
+resource: npm/rules/release/
+---
+
+# npm/rules/release
+
+| Файл                      | Тип       |
+| ------------------------- | --------- |
+| [change.mjs](change.md)   | JS Module |
+| [main.mjs](main.md)       | JS Module |
+| [release.mjs](release.md) | JS Module |

package/rules/release/docs/release.md

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: release.mjs
+resource: npm/rules/release/release.mjs
+docgen:
+  crc: 475bce65
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Файл автоматизує процес випуску версій. Він агрегує зміна-файли для всіх робочих просторів у `version-bump` та `CHANGELOG`, комітить зміни, ставить тег `<name>@<version>` та видаляє використані зміна-файли. Цей процес виконується у CI на гілці `main` (n-rules-release-design, варіант A). Публічні функції, що надає модуль, — `release` та `runReleaseCli`.
+
+## Поведінка
+
+release агрегує change-файли для всіх робочих просторів, оновлює версії в маніфестах, додає секції до `CHANGELOG.md`, видаляє використані change-файли, створює коміт та анотовані теги для всіх зібраних релізів, а потім намагається пушити їх у апстрім з повторними спробами.
+runReleaseCli виконує процес релізу, викликаючи функцію release, та виводить відповідний статус у консоль.
+
+## Публічний API
+
+release — агрегує change-файли для кожного робочого простору у version-bump та CHANGELOG, комітить зміни, ставить тег `<name>@<version>` та видаляє використані change-файли.
+runReleaseCli — виконує команди командного інтерфейсу для запуску процесу випуску.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)