@7n/rules 1.49.8 → 1.49.9

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.49.9] - 2026-07-26
+
+### Changed
+
+- Add configurable Git delta policy
+
 ## [1.49.8] - 2026-07-26
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.49.8",
+  "version": "1.49.9",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/changelog/consistency/comparison-models.mdc

@@ -15,14 +15,14 @@
 
 ### local-only
 
-**npm:** `private: true` або без `files`. **Python:** без пари name+version для реєстру. База залежить від гілки:
+**npm:** `private: true` або без `files`. **Python:** без пари name+version для реєстру. Гілки визначає `.n-rules.json:git`: `baseBranch` (за замовчуванням `main`) і `releaseBranches` (за замовчуванням `["main"]`). На обох значеннях за замовчуванням блок `git` у конфіг не пишуть.
 
-1. На **`dev`** local-only не активний (крім незакомічених registry-published).
-2. На **`main`** — diff від **`origin/main`** (попередній опублікований `main`); без remote — від `HEAD~1`. **`dev` не використовується** як база на `main`.
-3. На **feature-гілці** — merge-base з **`dev`**, якщо є; інакше з **`main`** (репо без `dev`). За наявності `origin/*` беремо новішу з двох баз (локальна гілка-кандидат vs `origin/`-версія) — застарілий локальний `main`/`dev` не має перекривати вже інтегровану в origin історію, і навпаки.
+1. На **`baseBranch`** local-only не активний (крім незакомічених registry-published).
+2. На гілці з **`releaseBranches`** — diff від її `origin/<branch>`; без remote — від `HEAD~1`.
+3. На feature-гілці — merge-base з кандидатами `baseBranch` і `releaseBranches`. Для кожного кандидата локальна та `origin/`-версії порівнюються, береться новіша спільна база; порядок кандидатів детермінований конфігом.
 4. Drift `version` від бази → **fail** (ручний bump заборонено). Зміни фіксуй change-файлом; bump зробить CI.
 
-Якщо немає git або немає `dev`/`main`/`origin/main` — local-only пропускається.
+Якщо немає git або refs із Git policy — local-only пропускається.
 
 Merge-коміт (готовий, з другим предком, або `MERGE_HEAD` під час незавершеного `git commit`) пропускається цілком — changeset документують feature-коміти, а не інтеграційний merge.
 

package/rules/changelog/consistency/docs/index.md

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

package/rules/changelog/consistency/docs/main.md

@@ -3,39 +3,31 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/changelog/consistency/main.mjs
 docgen:
-  crc: 59dac7bd
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 75
-  issues: internal-name:checkPublishedWorkspace,internal-name:runLocalOnlyChecks,anchor-miss:(n-changelog.mdc),judge:inaccurate:0.99
+  crc: 40857795
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 95
+  issues: anchor-miss:(n-changelog.mdc),judge-refine:kept-original,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Огляд:
-Цей файл гарантує готовність пакетів у монорепозиторії до публікації. Він сканує кореневі директорії, визначає локальні та зареєстровані пакети, використовуючи інформацію з конфігураційного файлу res.json. Далі він порівнює версію кожного пакета з даними, опублікованими на https://pypi.org/pypi/, та виконує локальні перевірки змін за допомогою Git.
-
-Поведінка:
-Ініціалізує процес перевірки, який аналізує кореневі директорії проєктів монорепозиторію. Проходиться по знайдених директоріях, визначаючись пакети з реєстру та локальні. Для кожного пакета, які можуть бути опубліковані в реєстрі, здійснюється перевірка відповідності `CHANGELOG.md` та порівняння версії з опублікованою через звернення до мережі. Якщо пакети не є опублікованими, виконується перевірка локальних змін на основі інформації з Git. Якщо виявлені зміни, і пакет не має файлу `.changes/CHANGELOG.md`, створюється цей файл з дефолтними даними. При виявленні розбіжностей версій виводиться повідомлення про заборону. Усі операції перехоплюють помилки (fail-safe), не генеруючи зовнішніх винятків, і повертають порожнє значення замість них за певних умов. Фінальний код виходу визначається на основі результатів перевірок.
+`lint` перевіряє, чи workspace справді потребує changelog-запису або bump, щоб не реагувати на merge-сценарії, застарілу базу та шум від ігнорованих шляхів. Для published workspace він звіряє локальний стан із уже опублікованою версією. Функція працює fail-safe: перехоплює помилки, не кидає їх назовні та за окремих збоїв повертає порожнє значення замість винятку.
 
 ## Поведінка
 
-Поведінка:
-
-1. Викликається `main`.
-2. Merge пропускається цілком: і готовий merge-коміт (HEAD із другим предком), і merge У ПРОЦЕСІ (маркер `MERGE_HEAD` під час `git commit` у pre-commit hook, коли `HEAD^2` ще не існує) — changeset документують feature-коміти, autofix шумного «Merge…»-changeset не створює.
-3. Знаходяться кореневі директорії проєктів монорепо.
-4. Проходиться по знайдених директоріях, визначаються пакети з реєстру та ті, що є локальними.
-5. База порівняння feature-гілки — НОВІШИЙ merge-base серед локальної та `origin/`-версії базової гілки (dev/main): застарілий локальний `main` не видає реліз-коміти, вже інтегровані в origin, за «ручний bump поза CI»; локальний main попереду origin так само валідний; репо без remote працює на локальних гілках.
-6. Для кожного пакета, які можуть бути опубліковані в реєстрі, викликається `checkPublishedWorkspace`.
-7. `checkPublishedWorkspace` перевіряє наявність та відповідність `CHANGELOG.md`, а також порівнює версію пакета з опублікованою версією через мережевий запит до https://pypi.org/pypi/.
-8. Якщо пакети не є опублікованими, викликається `runLocalOnlyChecks` для перевірки змін.
-9. `runLocalOnlyChecks` використовує інформацію з Git для порівняння поточного стану з базою гілки.
-10. Якщо виявлені зміни, і пакет не має файлу `.changes/CHANGELOG.md`, то в режимі автоматичного виправлення створюється цей файл з дефолтними даними.
-11. При виявленні різниці версій, яка свідчить про ручний збій (version вищий, ніж опублікований), виводиться повідомлення про заборону.
-12. `main` повертає код виходу на основі результатів перевірок.
+1. Перевіряє, чи репозиторій перебуває в merge-сценарії, і якщо так — не вважає це дефектом changelog-дисципліни: merge вже несе задокументовані зміни, тому окремий change-файл тут не потрібен.
+2. Визначає базу порівняння для changelog-навігації так, щоб брати найновішу з локальної та remote-версії базової гілки; це зменшує хибні спрацювання на застарілому локальному `main`/`dev` і коректно працює, коли remote відсутній.
+3. Для кожного workspace оцінює, чи є релевантні зміни відносно цієї бази, і відсікає шум від ігнорованих changelog-шляхів та ignore-правил. Це потрібно, щоб перевірка реагувала лише на зміни, які справді потребують bump або change-файлу.
+4. Для published workspace перевіряє, що changelog присутній і має базовий формат, а також що опублікована версія не відстає від локальної. Якщо версія в дереві випереджає опубліковану — це вважається ручним bump поза CI, а не штатним станом.
+5. Якщо published workspace має релевантні Git-зміни без change-файлу, або фіксує це як помилку, або в autofix-режимі створює change-файл із автоматичним описом і ставить його в індекс, щоб коміт не падав. Для published-пакетів додатково вимагається, щоб `files` у маніфесті містив `CHANGELOG.md`, бо релізний changelog має публікуватися разом із пакетом.
+6. Для workspace, які змінюються лише локально, звіряє версію з базою порівняння, перевіряє наявність незрелізних change-файлів і, якщо треба, також пропонує або створює change-файл. Повідомлення формуються в стилі, сумісному з правилами ``.
+7. Резолвить опубліковану версію залежно від типу пакета: для Python орієнтується на PyPI, для інших — на npm. Пошук публікації йде через `https://pypi.org/pypi/`, а також через конфігурацію `res.json`, якщо вона визначає очікувану поведінку workspace.
+8. Працює fail-safe: мережеві чи git-помилки не пробиваються назовні як винятки, а перетворюються на м’який результат або перевірочний фейл, щоб один збій не ламав увесь lint-прогін.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
 - За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/changelog/consistency/main.mjs

@@ -6,6 +6,7 @@ import { join } from 'node:path'
 import { promisify } from 'node:util'
 
 import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+import { readGitPolicy } from '../../../scripts/lib/git-policy.mjs'
 import {
   getMonorepoProjectRootDirs,
   manifestFilePath,
@@ -35,12 +36,6 @@ const AUTOFIX_SECTION = 'Changed'
 /** Fallback-опис, коли subject останнього коміту порожній (напр. порожній репозиторій). */
 const AUTOFIX_FALLBACK_MESSAGE = 'оновлення'
 
-/** Кандидати інтеграційними тести гілки для feature-гілок (перша наявна; див. n-changelog.mdc). */
-const FEATURE_BASE_BRANCH_CANDIDATES = Object.freeze(['dev', 'main'])
-
-/** Гілка `dev`: local-only не активний (крім незакомічених registry-published). */
-const LOCAL_ONLY_SKIP_BRANCH = 'dev'
-
 /**
  * Префікси шляхів (posix), які не вважаються релізними змінами — інверсія glob (n-changelog.mdc):
  * документація (`docs/`, `doc/`) та синхронізований із `@7n/rules` інструментарій
@@ -191,28 +186,30 @@ async function resolveMergeBase(baseRef, cwd) {
  * @returns {Promise<{ ref: string, label: string } | null>} результат
  */
 async function resolveChangelogComparisonPoint(branch, cwd) {
-  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
+  const policy = readGitPolicy(cwd)
+  if (branch === policy.baseBranch) {
     return null
   }
 
-  if (branch === 'main') {
-    const originMainRaw = await gitOrNull(['rev-parse', '--verify', '--quiet', 'origin/main'], cwd)
-    const originMainSha = originMainRaw?.trim()
+  if (policy.releaseBranches.includes(branch ?? '')) {
+    const originRef = `origin/${branch}`
+    const originRaw = await gitOrNull(['rev-parse', '--verify', '--quiet', originRef], cwd)
+    const originSha = originRaw?.trim()
     const headRaw = await gitOrNull(['rev-parse', 'HEAD'], cwd)
     const headSha = headRaw?.trim()
-    if (originMainSha && headSha && (originMainSha === headSha || (await isGitAncestor('origin/main', 'HEAD', cwd)))) {
-      return { ref: 'origin/main', label: 'main' }
+    if (originSha && headSha && (originSha === headSha || (await isGitAncestor(originRef, 'HEAD', cwd)))) {
+      return { ref: originRef, label: branch }
     }
     const parent = await gitOrNull(['rev-parse', '--verify', '--quiet', 'HEAD~1'], cwd)
     if (typeof parent === 'string' && parent.trim().length > 0) {
-      return { ref: parent.trim(), label: 'main~1' }
+      return { ref: parent.trim(), label: `${branch}~1` }
     }
     return null
   }
 
   // Feature-гілка: база — новіший merge-base серед локальної та origin-версії кандидата
   // (див. resolveNewestMergeBase; застарілий локальний main не має перекривати origin).
-  for (const name of FEATURE_BASE_BRANCH_CANDIDATES) {
+  for (const name of policy.integrationBranches) {
     const mergeBase = await resolveNewestMergeBase(name, cwd)
     if (!mergeBase) {
       continue
@@ -591,7 +588,8 @@ async function checkPublishedWorkspacePendingGitChanges(manifest, _Vcurrent, sub
 
   const branch = await currentBranchName(cwd)
 
-  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
+  const policy = readGitPolicy(cwd)
+  if (branch === policy.baseBranch) {
     if (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces, cwd)) {
       await fixOrFailPublishedWorkspace(manifest, label, mf, autofix, pass, fail, cwd)
     }
@@ -604,7 +602,7 @@ async function checkPublishedWorkspacePendingGitChanges(manifest, _Vcurrent, sub
     return
   }
 
-  if (branch === 'main' && (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces, cwd))) {
+  if (policy.releaseBranches.includes(branch ?? '') && (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces, cwd))) {
     await fixOrFailPublishedWorkspace(manifest, label, mf, autofix, pass, fail, cwd)
   }
 }
@@ -732,13 +730,14 @@ async function runLocalOnlyChecks(localOnly, subWorkspaces, autofix, pass, fail,
     return
   }
   const branch = await currentBranchName(cwd)
-  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
-    pass('changelog: поточна гілка = dev — local-only перевірку пропущено')
+  const policy = readGitPolicy(cwd)
+  if (branch === policy.baseBranch) {
+    pass(`changelog: поточна гілка = ${policy.baseBranch} — local-only перевірку пропущено`)
     return
   }
   const comparison = await resolveChangelogComparisonPoint(branch, cwd)
   if (!comparison) {
-    pass('changelog: ref dev/main (та origin/*) не знайдено — local-only перевірку пропущено')
+    pass('changelog: Git policy refs (та origin/*) не знайдено — local-only перевірку пропущено')
     return
   }
 

package/schemas/n-rules.json

@@ -59,6 +59,24 @@
         "minLength": 1
       }
     },
+    "git": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Git policy проєкту. Відсутній блок еквівалентний baseBranch/releaseBranches = main.",
+      "properties": {
+        "baseBranch": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Головна integration-гілка і перший кандидат бази delta; за замовчуванням main."
+        },
+        "releaseBranches": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Довгоживучі release/integration гілки; разом з baseBranch утворюють delta та protected набір. За замовчуванням [main].",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
     "version": {
       "type": "string",
       "description": "Застаріле поле, ігнорується CLI. Правила завжди копіюються з каталогу mdc/ установленого пакету (node_modules або кеш npx); змініть версію через оновлення залежності."

package/scripts/lib/changed-files.mjs

@@ -8,6 +8,7 @@
 import { spawnSync } from 'node:child_process'
 
 import { isWorktreeCheckoutPath } from '../utils/walkDir.mjs'
+import { readGitPolicy } from './git-policy.mjs'
 
 /**
  * @param {string[]} args аргументи git
@@ -47,18 +48,16 @@ function dropWorktreeCheckouts(paths) {
 
 /**
  * Визначає git base для scoped-перевірок без зовнішнього runtime-стану.
- * Кандидати — `origin/main` і локальна `main`: рахуємо merge-base з HEAD для обох
- * і беремо **новіший** (descendant) з двох. Це захищає від stale-ref з будь-якого
- * боку: у git-worktree локальна `main` закріплена за іншим деревом і часто відстає
- * (застаріла база → фантомні «змінені» файли з давно влитих PR), а без свіжого
- * fetch може відставати вже `origin/main`. Якщо доступний лише один ref (офлайн,
- * без remote) — його merge-base; якщо жодного — null, і caller порівнює лише
+ * Кандидати — effective Git policy: `baseBranch` + `releaseBranches`, кожна у
+ * `origin/` та локальній формах. Беремо **найновіший** сумісний merge-base; це
+ * захищає від stale-ref і вже інтегрованих змін між довгоживучими середовищами.
+ * Якщо жодного ref немає — null, і caller порівнює лише
  * робоче дерево з HEAD. Повернений sha завжди досяжний (це merge-base існуючого
  * ref), тож fail-closed перевірка в `collectChangedFilesSince` не спрацює хибно.
- * Явний `baseRef` (CI: `--base origin/main` після fetch) вимикає вибір —
+ * Явний `baseRef` (CI: `--base origin/dev` після fetch) вимикає вибір —
  * merge-base рахується лише проти нього.
  * @param {string} [cwd] корінь репо
- * @param {string|null} [baseRef] явний ref бази замість вибору origin/main|main
+ * @param {string|null} [baseRef] явний ref бази замість Git policy
  * @returns {string|null} merge-base commit або null
  */
 export function resolveChangedBase(cwd = process.cwd(), baseRef = null) {
@@ -67,12 +66,16 @@ export function resolveChangedBase(cwd = process.cwd(), baseRef = null) {
     return result.status === 0 && !result.error ? result.stdout.trim() : ''
   }
   if (baseRef) return mergeBaseWith(baseRef) || null
-  const [primary, secondary] = ['origin/main', 'main'].map(ref => mergeBaseWith(ref)).filter(Boolean)
-  if (!primary || !secondary || primary === secondary) return primary ?? null
-  // Обидва ref-и дали різні merge-base: новіший — той, що є нащадком іншого.
-  // Якщо гілки merge-base розійшлися (екзотика), лишаємо пріоритет origin/main.
-  const ancestry = spawnSync('git', ['merge-base', '--is-ancestor', primary, secondary], { cwd })
-  return ancestry.status === 0 && !ancestry.error ? secondary : primary
+  const { integrationBranches } = readGitPolicy(cwd)
+  const bases = integrationBranches.flatMap(name => [`origin/${name}`, name]).map(mergeBaseWith).filter(Boolean)
+  if (bases.length === 0) return null
+  let newest = bases[0]
+  for (const candidate of bases.slice(1)) {
+    if (candidate === newest) continue
+    const ancestry = spawnSync('git', ['merge-base', '--is-ancestor', newest, candidate], { cwd })
+    if (ancestry.status === 0 && !ancestry.error) newest = candidate
+  }
+  return newest
 }
 
 /**

package/scripts/lib/docs/changed-files.md

@@ -3,33 +3,50 @@ type: JS Module
 title: changed-files.mjs
 resource: npm/scripts/lib/changed-files.mjs
 docgen:
-  crc: 1c7d9027
+  crc: 0482c036
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
+  issues: judge-refine:kept-original,judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Файл збирає змінені та незакомічені файли з робочого дерева. Визначає базовий комміт для перевірок у межах зміненого діапазону. Збирає змінені та незакомічені файли відносно базового комміту.
+## Огляд
+
+Файл збирає перелік файлів для quick-режиму lint-оркестратора: змінені та staged через `git diff HEAD`, а також нові untracked через `git ls-files --others --exclude-standard`. Видалені файли не потрапляють у результат.
+
+`collectChangedFiles`, `resolveChangedBase` і `collectChangedFilesSince` потрібні, щоб визначати базу порівняння та повертати лише актуально змінені робочі файли для перевірки. Поза git-репо або при помилці git повертається порожній список.
 
 ## Поведінка
 
-collectChangedFiles Збирає змінені та незакомічені файли з робочого дерева.
-resolveChangedBase Визначає базовий комміт для scoped-перевірок.
-collectChangedFilesSince Збирає змінені та незакомічені файли відносно базового комміту.
+`collectChangedFiles` формує scope quick-перевірки з поточного робочого дерева: бере змінені tracked/staged файли відносно `HEAD`, додає нові untracked файли та повертає унікальні relative-posix шляхи без видалених файлів.
+
+`resolveChangedBase` потрібна перед scoped-перевірками, коли scope має рахуватися не лише від `HEAD`, а від інтеграційної бази. Вона визначає досяжний merge-base для поточної гілки: або за явно заданим base ref, або за політикою git-гілок репозиторію. Якщо придатної бази немає, результатом є відсутність бази, і подальший збір змін має перейти до quick-поведінки.
+
+`collectChangedFilesSince` споживає базу з `resolveChangedBase` або її відсутність. За наявної бази вона збирає всі файли, змінені від цієї бази до поточного робочого дерева, включно із закоміченими після бази, staged і незакоміченими змінами, та додає untracked файли. За відсутньої бази делегує збір до `collectChangedFiles`.
+
+Усі результати є списками унікальних шляхів для наступних lint-етапів. Для обох режимів діє спільне правило: видалені файли не потрапляють у scope, а файли всередині службових worktree-чекаутів відкидаються, щоб сесійні копії репозиторію не лінтилися як робочий код. Поза git-репозиторієм або при помилці git звичайний quick-збір повертає порожній список, але scoped-збір із недосяжною базою завершується явною помилкою, щоб перевірка не пройшла з порожнім scope помилково.
 
 ## Публічний API
 
-- collectChangedFiles: Збирає список змінених та невідстежених файлів з робочого дерева відносно робочого дерева.
-- resolveChangedBase: Визначає базовий комміт для обмежених перевірок без використання зовнішнього стану.
-  - Кандидати — `origin/main` і локальна `main`: merge-base з HEAD рахується для обох, береться новіший (descendant). Це захищає від stale-ref: у git-worktree локальна `main` часто відстає, без свіжого fetch може відставати `origin/main`.
-  - Явний другий аргумент `baseRef` (CI: `--base origin/main`) вимикає вибір — merge-base рахується лише проти нього.
-  - Якщо доступний лише один ref (офлайн/без remote) — його merge-base; якщо ref-и відсутні, повертає null, і викликаючий порівнює лише робоче дерево з HEAD.
-- collectChangedFilesSince: Збирає список змінених та невідстежених файлів відносно базового комміту.
-- git diff <base>: Порівнює комміт `base` з поточним робочим деревом (включаючи закомічені та незакомічені модифікації).
-  - Якщо `base` відсутній, використовується `collectChangedFiles`.
+- collectChangedFiles — Relative-posix список змінених + untracked файлів робочого дерева.
+- resolveChangedBase — Визначає git base для scoped-перевірок без зовнішнього runtime-стану.
+Кандидати — effective Git policy: `baseBranch` + `releaseBranches`, кожна у
+`origin/` та локальній формах. Беремо **найновіший** сумісний merge-base; це
+захищає від stale-ref і вже інтегрованих змін між довгоживучими середовищами.
+Якщо жодного ref немає — null, і caller порівнює лише
+робоче дерево з HEAD. Повернений sha завжди досяжний (це merge-base існуючого
+ref), тож fail-closed перевірка в `collectChangedFilesSince` не спрацює хибно.
+Явний `baseRef` (CI: `--base origin/dev` після fetch) вимикає вибір —
+merge-base рахується лише проти нього.
+- collectChangedFilesSince — Список змінених + untracked файлів **відносно базового комміту**.
+
+`git diff <base>` (без `..`/`...`, без `HEAD`) порівнює base-комміт із поточним
+**робочим деревом** — тобто однаково ловить і закомічене від base, і staged, і
+незакомічені модифікації. Це гарантує однакову поведінку незалежно від того, чи
+зміни вже закомічені у worktree. Без `base` — fallback на `collectChangedFiles`
+(робоче дерево vs HEAD).
 
 ## Гарантії поведінки
 
-- Обидва збирачі відкидають шляхи всередині worktree-чекаутів (`.worktrees/`, `.claude/worktrees/`): це повні копії репо (сесійні git-worktree Claude/агентів), а не робочий код; у споживацьких репо вони можуть бути не gitignored і інакше потрапляли б у delta-список як untracked.
-
-- Read-only: файл не виконує операцій запису у файлову систему.
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.
+- (специфічних машинно-виведених гарантій немає)

package/scripts/lib/docs/git-policy.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: git-policy.mjs
+resource: npm/scripts/lib/git-policy.mjs
+docgen:
+  crc: 5809ac19
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`readGitPolicy` читає Git policy проєкту з `.n-rules.json` або `.n-cursor.json`, щоб delta-перевірки, changelog і branch tooling користувалися спільним набором базової, release, integration і protected гілок. Якщо політика відсутня, неповна або непридатна, повертає історичний канон `main`, не зупиняючи роботу інструментів. Помилки перехоплюються і не кидаються назовні.
+
+## Поведінка
+
+1. `readGitPolicy` шукає компактну політику Git у конфігах `.n-rules.json`, `.n-cursor.json`, щоб узгодити базову, release, integration і protected гілки для delta-перевірок, changelog і branch tooling.
+2. Якщо конфіг відсутній, неповний або не може бути прочитаний як валідні дані, функція безпечно повертається до історичного канону `main` і не перериває роботу інструментів винятком.
+3. Базова гілка береться з політики лише тоді, коли вона задана змістовним іменем; інакше використовується `main`.
+4. Release-гілки беруться з політики як набір змістовних унікальних назв; якщо придатних значень немає, release-набором стає `main`.
+5. Integration-гілки формуються як об’єднання базової гілки та release-гілок без дублювання, щоб downstream-інструменти мали єдине джерело правди для порівнянь.
+6. Protected-гілки збігаються з integration-гілками, бо ці довгоживучі гілки мають однаково враховуватися як цільові й захищені.
+
+## Публічний API
+
+- readGitPolicy — Повертає effective policy. `releaseBranches` одночасно є integration-кандидатами
+delta та захищеними довгоживучими гілками; `baseBranch` додається до обох наборів.
+
+## Гарантії поведінки
+
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/scripts/lib/docs/index.md

@@ -20,6 +20,7 @@ resource: npm/scripts/lib/
 | [ensure-tool.mjs](ensure-tool.md)                                           | JS Module |
 | [generated-markdown.mjs](generated-markdown.md)                             | JS Module |
 | [gha-workflow.mjs](gha-workflow.md)                                         | JS Module |
+| [git-policy.mjs](git-policy.md)                                             | JS Module |
 | [glob-to-regex.mjs](glob-to-regex.md)                                       | JS Module |
 | [inline-template-links.mjs](inline-template-links.md)                       | JS Module |
 | [js-source-signals.mjs](js-source-signals.md)                               | JS Module |

package/scripts/lib/git-policy.mjs

@@ -0,0 +1,45 @@
+/**
+ * Читає компактну Git policy проєкту для delta, changelog і branch tooling.
+ * Відсутній або неповний конфіг зберігає історичний канон `main`.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const CONFIG_FILES = ['.n-rules.json', '.n-cursor.json']
+const DEFAULT_BASE_BRANCH = 'main'
+
+/**
+ * @param {unknown} value потенційне ім'я гілки
+ * @returns {string|null} нормалізоване ім'я або null
+ */
+function branchName(value) {
+  if (typeof value !== 'string') return null
+  const name = value.trim()
+  return name.length > 0 ? name : null
+}
+
+/**
+ * Повертає effective policy. `releaseBranches` одночасно є integration-кандидатами
+ * delta та захищеними довгоживучими гілками; `baseBranch` додається до обох наборів.
+ * @param {string} [cwd] корінь репозиторію
+ * @returns {{baseBranch:string,releaseBranches:string[],integrationBranches:string[],protectedBranches:string[]}}
+ */
+export function readGitPolicy(cwd = process.cwd()) {
+  let raw = null
+  for (const file of CONFIG_FILES) {
+    const path = join(cwd, file)
+    if (!existsSync(path)) continue
+    try {
+      raw = JSON.parse(readFileSync(path, 'utf8'))
+    } catch {
+      // Повний CLI повідомить про невалідний JSON; standalone helpers лишаються safe-by-default.
+    }
+    break
+  }
+  const git = raw && typeof raw.git === 'object' && !Array.isArray(raw.git) ? raw.git : {}
+  const baseBranch = branchName(git.baseBranch) ?? DEFAULT_BASE_BRANCH
+  const configuredRelease = Array.isArray(git.releaseBranches) ? git.releaseBranches.map(branchName).filter(Boolean) : []
+  const releaseBranches = configuredRelease.length > 0 ? [...new Set(configuredRelease)] : [DEFAULT_BASE_BRANCH]
+  const integrationBranches = [...new Set([baseBranch, ...releaseBranches])]
+  return { baseBranch, releaseBranches, integrationBranches, protectedBranches: integrationBranches }
+}

package/skills/git-reconcile/js/orchestrate.mjs

@@ -6,8 +6,8 @@ import { performance } from 'node:perf_hooks'
 import { env } from 'node:process'
 
 import { createProgressReporter } from '../../../scripts/lib/lint-surface/progress.mjs'
+import { readGitPolicy } from '../../../scripts/lib/git-policy.mjs'
 
-const BASE_REF = 'origin/main'
 const LLM_TIERS = ['min', 'max']
 const REVIEW_BATCH_SIZE = 10
 const PROMPT_TEXT_LIMIT = 12_000
@@ -30,6 +30,11 @@ function noop() {
   // Навмисно порожньо: caller не запросив progress output.
 }
 
+/** @param {string} cwd корінь репозиторію @returns {string} remote ref базової гілки */
+function policyBaseRef(cwd) {
+  return `origin/${readGitPolicy(cwd).baseBranch}`
+}
+
 /**
  * Форматує elapsed time без удаваної точності.
  * @param {number} startedAt початок у мілісекундах
@@ -178,10 +183,10 @@ function branchName(ref) {
  * @param {Map<string,string>} worktreeCommits checkout HEAD OID→path
  * @returns {Array<{ref:string, oid:string, date:string, worktree:string|null,aliases:string[]}>} refs
  */
-export function dedupeRefs(refs, worktrees, worktreeCommits = new Map()) {
+export function dedupeRefs(refs, worktrees, worktreeCommits = new Map(), protectedBranches = ['main']) {
   const byOid = new Map()
   for (const item of refs) {
-    if (item.ref === 'refs/remotes/origin/HEAD' || branchName(item.ref) === 'main') continue
+    if (item.ref === 'refs/remotes/origin/HEAD' || protectedBranches.includes(branchName(item.ref))) continue
     const existing = byOid.get(item.oid)
     const worktree = worktrees.get(item.ref) ?? worktreeCommits.get(item.oid) ?? existing?.worktree ?? null
     const isRemote = item.ref.startsWith('refs/remotes/origin/')
@@ -282,8 +287,10 @@ export function conflictFiles(text) {
  */
 export function inventoryRepository(cwd, deps = {}) {
   const spawnFn = deps.spawnFn ?? spawnSync
+  const policy = readGitPolicy(cwd)
+  const baseRef = policyBaseRef(cwd)
   git(['fetch', '--prune', 'origin'], cwd, spawnFn)
-  git(['rev-parse', '--verify', BASE_REF], cwd, spawnFn)
+  git(['rev-parse', '--verify', baseRef], cwd, spawnFn)
 
   const worktreeState = parseWorktreeState(git(['worktree', 'list', '--porcelain'], cwd, spawnFn).stdout)
   const refLines = git(
@@ -299,7 +306,8 @@ export function inventoryRepository(cwd, deps = {}) {
       return { ref, oid, date }
     }),
     worktreeState.branches,
-    worktreeState.commits
+    worktreeState.commits,
+    policy.protectedBranches
   )
   const prInventory = openPullRequests(cwd, spawnFn)
   const prs = prInventory.items
@@ -308,16 +316,16 @@ export function inventoryRepository(cwd, deps = {}) {
   const branches = refs.map(item => {
     const name = branchName(item.ref)
     const merged =
-      git(['merge-base', '--is-ancestor', item.ref, BASE_REF], cwd, spawnFn, {
+      git(['merge-base', '--is-ancestor', item.ref, baseRef], cwd, spawnFn, {
         allowFailure: true
       }).status === 0
     const novelCommitIds = merged
       ? []
-      : git(['rev-list', '--right-only', '--cherry-pick', '--no-merges', `${BASE_REF}...${item.ref}`], cwd, spawnFn)
+      : git(['rev-list', '--right-only', '--cherry-pick', '--no-merges', `${baseRef}...${item.ref}`], cwd, spawnFn)
           .stdout.split('\n')
           .filter(Boolean)
           .toReversed()
-    const counts = git(['rev-list', '--left-right', '--count', `${BASE_REF}...${item.ref}`], cwd, spawnFn)
+    const counts = git(['rev-list', '--left-right', '--count', `${baseRef}...${item.ref}`], cwd, spawnFn)
       .stdout.trim()
       .split(WHITESPACE_RE)
       .map(Number)
@@ -325,13 +333,13 @@ export function inventoryRepository(cwd, deps = {}) {
     const state = branchState({ merged, novelCommitIds, pr, worktree: item.worktree })
     const changedFiles =
       state === 'review'
-        ? git(['diff', '--name-status', `${BASE_REF}...${item.ref}`], cwd, spawnFn)
+        ? git(['diff', '--name-status', `${baseRef}...${item.ref}`], cwd, spawnFn)
             .stdout.split('\n')
             .filter(Boolean)
             .slice(0, 200)
         : []
     const mergeTree =
-      state === 'review' ? git(['merge-tree', BASE_REF, item.ref], cwd, spawnFn, { allowFailure: true }).stdout : ''
+      state === 'review' ? git(['merge-tree', baseRef, item.ref], cwd, spawnFn, { allowFailure: true }).stdout : ''
     return {
       source: `${SOURCE_BRANCH_PREFIX}${item.ref}`,
       ref: item.ref,
@@ -364,7 +372,7 @@ export function inventoryRepository(cwd, deps = {}) {
     }
   })
 
-  return { base: BASE_REF, branches, stashes, warnings }
+  return { base: baseRef, baseBranch: policy.baseBranch, branches, stashes, warnings }
 }
 
 /**
@@ -629,7 +637,7 @@ function chooseBranch(title, cwd, spawnFn) {
 
 /**
  * Створює керований worktree та детерміновано пересаджує його branch на
- * origin/main без зміни вихідного checkout.
+ * policy base ref без зміни вихідного checkout.
  * @param {string} title PR title
  * @param {string} source source id
  * @param {string} cwd корінь
@@ -637,11 +645,12 @@ function chooseBranch(title, cwd, spawnFn) {
  * @returns {{branch:string,cwd:string}} worktree
  */
 function createReconcileWorktree(title, source, cwd, spawnFn) {
+  const baseRef = policyBaseRef(cwd)
   const branch = chooseBranch(title, cwd, spawnFn)
   run('npx', ['@7n/mt', 'worktree', 'create', branch, `git-reconcile: ${source}`], cwd, spawnFn)
   const worktreeCwd = join(cwd, '.worktrees', branch.replaceAll('/', '-'))
-  git(['switch', '--detach', BASE_REF], worktreeCwd, spawnFn)
-  git(['branch', '-f', branch, BASE_REF], worktreeCwd, spawnFn)
+  git(['switch', '--detach', baseRef], worktreeCwd, spawnFn)
+  git(['branch', '-f', branch, baseRef], worktreeCwd, spawnFn)
   git(['switch', branch], worktreeCwd, spawnFn)
   return { branch, cwd: worktreeCwd }
 }
@@ -718,11 +727,12 @@ export function finishCherryPick(cwd, spawnFn = spawnSync) {
  * @returns {boolean} чи є що переносити в PR
  */
 export function hasChangesFromBase(cwd, spawnFn = spawnSync) {
+  const baseRef = policyBaseRef(cwd)
   return (
-    git(['diff', '--quiet', `${BASE_REF}...HEAD`], cwd, spawnFn, {
+    git(['diff', '--quiet', `${baseRef}...HEAD`], cwd, spawnFn, {
       allowFailure: true
     }).status !== 0 ||
-    git(['diff', '--quiet', BASE_REF, '--'], cwd, spawnFn, {
+    git(['diff', '--quiet', baseRef, '--'], cwd, spawnFn, {
       allowFailure: true
     }).status !== 0 ||
     git(['ls-files', '--others', '--exclude-standard'], cwd, spawnFn).stdout.trim().length > 0
@@ -795,13 +805,13 @@ export function sourceDirectories(paths) {
 }
 
 /**
- * Збирає tracked і untracked code directories відносно origin/main.
+ * Збирає tracked і untracked code directories відносно policy base ref.
  * @param {string} cwd worktree
  * @param {typeof spawnSync} spawnFn інжект
  * @returns {string[]} directories
  */
 function changedPaths(cwd, spawnFn) {
-  const tracked = git(['diff', '--name-only', BASE_REF, '--'], cwd, spawnFn).stdout.split('\n').filter(Boolean)
+  const tracked = git(['diff', '--name-only', policyBaseRef(cwd), '--'], cwd, spawnFn).stdout.split('\n').filter(Boolean)
   const untracked = git(['ls-files', '--others', '--exclude-standard'], cwd, spawnFn).stdout.split('\n').filter(Boolean)
   return [...new Set([...tracked, ...untracked])]
 }
@@ -874,7 +884,7 @@ function ensureWorktreeDependencies(cwd, spawnFn) {
 }
 
 /**
- * Фіксує test baseline на чистому origin/main до перенесення source.
+ * Фіксує test baseline на чистій policy base гілці до перенесення source.
  * @param {string} cwd worktree
  * @param {typeof spawnSync} spawnFn інжект
  * @returns {{tests:{status:number,stdout:string,stderr:string}|null}} baseline
@@ -889,7 +899,7 @@ export function captureBehaviorBaseline(cwd, spawnFn = spawnSync) {
 }
 
 /**
- * Повторно використовує test baseline одного origin/main між PR-групами.
+ * Повторно використовує test baseline однієї policy base гілки між PR-групами.
  * Залежності все одно встановлюються в кожному окремому worktree.
  * @param {string} cwd worktree
  * @param {Map<string,object>} cache кеш за OID бази
@@ -898,7 +908,7 @@ export function captureBehaviorBaseline(cwd, spawnFn = spawnSync) {
  */
 export function captureCachedBehaviorBaseline(cwd, cache, spawnFn = spawnSync) {
   ensureWorktreeDependencies(cwd, spawnFn)
-  const baseOid = git(['rev-parse', BASE_REF], cwd, spawnFn).stdout.trim()
+  const baseOid = git(['rev-parse', policyBaseRef(cwd)], cwd, spawnFn).stdout.trim()
   if (cache.has(baseOid)) return { baseline: cache.get(baseOid), cached: true }
   const baseline = captureBehaviorBaseline(cwd, spawnFn)
   cache.set(baseOid, baseline)
@@ -910,7 +920,7 @@ export function captureCachedBehaviorBaseline(cwd, cache, spawnFn = spawnSync) {
  * Саме ці докази вирішують, чи приймати min-результат або ескалювати на max.
  * @param {string} cwd worktree
  * @param {typeof spawnSync} spawnFn інжект
- * @param {{tests:{status:number,stdout:string,stderr:string}|null}|null} [baseline] стан origin/main
+ * @param {{tests:{status:number,stdout:string,stderr:string}|null}|null} [baseline] стан policy base гілки
  * @param {(stage:string)=>void} [onProgress] stage callback
  * @returns {{ok:boolean,error?:string}} validation
  */
@@ -972,7 +982,7 @@ async function resolveConflict(args) {
   const { runner, source, worktreeCwd, deps, spawnFn, log, onProgress = noop } = args
   const unresolved = unresolvedFiles(worktreeCwd, spawnFn)
   const prompt = [
-    `У worktree ${worktreeCwd} JS уже застосував ${source} до свіжого origin/main.`,
+    `У worktree ${worktreeCwd} JS уже застосував ${source} до свіжої policy base гілки.`,
     `Розв'яжи лише змістові конфлікти: ${unresolved.join(', ')}.`,
     'Порівняй current main та намір перенесеної зміни; не використовуй ours/theirs механічно.',
     'Збережи актуальну поведінку main, перенеси лише відсутню корисну частину.',
@@ -1036,7 +1046,7 @@ async function applySource(args) {
 async function finalizeBehavior(args) {
   const { runner, source, rationale, worktreeCwd, baseline, deps, spawnFn, log, onProgress = noop } = args
   const prompt = [
-    `JS переніс ${source} на свіжий origin/main у ${worktreeCwd}.`,
+    `JS переніс ${source} на свіжу policy base гілку у ${worktreeCwd}.`,
     `Очікувана користь: ${rationale}`,
     'Перевір реальний diff і call sites. Доведи лише перенесену поведінку до готовності:',
     '- додай/онови regression test, якщо це bug fix;',
@@ -1140,7 +1150,9 @@ async function createPullRequest(args) {
     onProgress('delta lint')
     const finalGates = validateFinalProjectGates(worktree.cwd, spawnFn)
     if (!finalGates.ok) throw new Error(finalGates.error)
-    git(['diff', '--check', `${BASE_REF}...HEAD`], worktree.cwd, spawnFn)
+    const baseRef = policyBaseRef(worktree.cwd)
+    const baseBranch = readGitPolicy(worktree.cwd).baseBranch
+    git(['diff', '--check', `${baseRef}...HEAD`], worktree.cwd, spawnFn)
     onProgress('push')
     git(['push', '-u', 'origin', worktree.branch], worktree.cwd, spawnFn)
 
@@ -1148,10 +1160,10 @@ async function createPullRequest(args) {
     const body = [
       `Джерело: \`${source}\`.`,
       '',
-      group.rationale ?? candidate.rationale ?? 'Корисну поведінку перенесено на актуальний main.',
+      group.rationale ?? candidate.rationale ?? `Корисну поведінку перенесено на актуальний ${baseBranch}.`,
       '',
       'Перевірки:',
-      '- `git diff --check origin/main...HEAD`',
+      `- \`git diff --check ${baseRef}...HEAD\``,
       '- scoped code lint/tests та domain lint для non-code paths',
       '- `npx @7n/rules lint changelog --no-fix`',
       verification ? `- LLM behavioral verification: ${verification.slice(0, 1000)}` : ''
@@ -1160,7 +1172,7 @@ async function createPullRequest(args) {
       .join('\n')
     createdPr = run(
       'gh',
-      ['pr', 'create', '--base', 'main', '--head', worktree.branch, '--title', group.title, '--body', body],
+      ['pr', 'create', '--base', baseBranch, '--head', worktree.branch, '--title', group.title, '--body', body],
       worktree.cwd,
       spawnFn
     ).stdout.trim()