@7n/rules 1.0.0

package/scripts/lib/lint-surface/tier-sampling-experiment.mjs

@@ -0,0 +1,289 @@
+/**
+ * Експериментальний harness для перевірки sampling/consensus поверх lint fix ladder.
+ *
+ * Модуль не підключений до production `runFixPipeline`: він моделює isolated candidates
+ * для заданого tier-а, кожен раз відкочує робоче дерево до S1, вибирає тільки candidate,
+ * який пройшов canonical detect, і лишає judge/consensus лише джерелом feedback.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { createSnapshot } from './snapshot.mjs'
+
+export const EXPERIMENT_TIER_ORDER = Object.freeze(['local-min', 'cloud-min', 'cloud-avg', 'cloud-max'])
+
+const DEFAULT_LOCAL_TIMEOUT_MS = 300_000
+const DEFAULT_CLOUD_TIMEOUT_MS = 300_000
+
+const DEFAULT_PROFILES_BY_TIER = Object.freeze({
+  'local-min': ['conservative'],
+  'cloud-min': ['conservative', 'exploratory'],
+  'cloud-avg': ['conservative', 'exploratory'],
+  'cloud-max': ['conservative']
+})
+
+/**
+ * @typedef {object} ExperimentRung
+ * @property {'local-min'|'cloud-min'|'cloud-avg'|'cloud-max'} tier Ідентифікатор tier-а в експериментальному ladder.
+ * @property {string} model Назва моделі, що виконує fix на цьому rung-і.
+ * @property {boolean} feedback Чи передавати judge-feedback у контекст fix-у.
+ * @property {boolean} local Чи виконується rung локальною моделлю.
+ * @property {boolean} isAvg Чи це rung рівня cloud-avg.
+ * @property {boolean} isMax Чи це rung рівня cloud-max.
+ * @property {boolean} experimentOnly Позначка, що rung існує лише в експерименті, не в production ladder.
+ * @property {number} timeoutMs Стеля часу виконання одного кандидата, мс.
+ */
+
+/**
+ * @typedef {object} SamplingCandidate
+ * @property {string} id Унікальний ідентифікатор кандидата в межах прогону.
+ * @property {'conservative'|'exploratory'|'judge'|string} samplingProfile Sampling-профіль, з яким запускається кандидат.
+ */
+
+/**
+ * @typedef {object} CandidateAttempt
+ * @property {number} index Порядковий номер кандидата у списку.
+ * @property {string} id Ідентифікатор кандидата.
+ * @property {string} samplingProfile Sampling-профіль кандидата.
+ * @property {string} tier Tier rung-а, на якому виконувався кандидат.
+ * @property {string} model Модель, що виконувала fix.
+ * @property {boolean} clean Чи пройшов кандидат canonical detect без залишкових порушень.
+ * @property {string[]} touchedFiles Абсолютні шляхи файлів, які кандидат змінив.
+ * @property {number} changedBytes Сумарний розмір captured patch у байтах.
+ * @property {number} wallMs Тривалість спроби, мс.
+ * @property {string|null} error Повідомлення помилки worker-а або null.
+ * @property {import('./types.mjs').LintViolation[]} violations Порушення, що лишилися після спроби.
+ * @property {object|undefined} telemetry Телеметрія worker-а, якщо він її повернув.
+ * @property {Array<{ absPath: string, exists: boolean, content: string }>} patch Знімок змінених файлів чистого кандидата.
+ */
+
+/**
+ * Будує experiment-only ladder із `cloud-max`. Production ladder це не змінює.
+ * @param {{ localMin?: string, cloudMin?: string, cloudAvg?: string, cloudMax?: string }} models - Об'єкт, що містить імена моделей для кожного tier.
+ * @param {{ localTimeoutMs?: number, cloudTimeoutMs?: number }} [opts] - Опції для встановлення timeout для локального та хмарного етапу.
+ * @returns {ExperimentRung[]} Масив експериментальних rung'ів (етапів).
+ */
+export function buildExperimentLadder(models, opts = {}) {
+  const localTimeoutMs = opts.localTimeoutMs ?? DEFAULT_LOCAL_TIMEOUT_MS
+  const cloudTimeoutMs = opts.cloudTimeoutMs ?? DEFAULT_CLOUD_TIMEOUT_MS
+  return [
+    {
+      tier: 'local-min',
+      model: models.localMin ?? '',
+      feedback: false,
+      local: true,
+      isAvg: false,
+      isMax: false,
+      experimentOnly: true,
+      timeoutMs: localTimeoutMs
+    },
+    {
+      tier: 'cloud-min',
+      model: models.cloudMin ?? '',
+      feedback: true,
+      local: false,
+      isAvg: false,
+      isMax: false,
+      experimentOnly: true,
+      timeoutMs: cloudTimeoutMs
+    },
+    {
+      tier: 'cloud-avg',
+      model: models.cloudAvg ?? '',
+      feedback: true,
+      local: false,
+      isAvg: true,
+      isMax: false,
+      experimentOnly: true,
+      timeoutMs: cloudTimeoutMs
+    },
+    {
+      tier: 'cloud-max',
+      model: models.cloudMax ?? '',
+      feedback: true,
+      local: false,
+      isAvg: false,
+      isMax: true,
+      experimentOnly: true,
+      timeoutMs: cloudTimeoutMs
+    }
+  ].filter(r => r.model)
+}
+
+/**
+ * Повертає можливі sampling profiles для заданого tier-а.
+ * @param {string} tier - Назва tier (наприклад, 'local-min').
+ * @param {Record<string, Array<string|SamplingCandidate>>} [overrides] - Об'єкт з перевизначеними profiles для конкретного tier.
+ * @returns {SamplingCandidate[]} Масив об'єктів SamplingCandidate для даного tier.
+ */
+export function samplingProfilesForTier(tier, overrides = {}) {
+  const raw = overrides[tier] ?? DEFAULT_PROFILES_BY_TIER[tier] ?? ['conservative']
+  return raw.map((p, index) => {
+    if (typeof p === 'string') return { id: `${tier}:${p}:${index}`, samplingProfile: p }
+    return { id: p.id ?? `${tier}:${p.samplingProfile}:${index}`, samplingProfile: p.samplingProfile }
+  })
+}
+
+/**
+ * Дефолтний вибір найкращого (clean) кандидата серед усіх спроб.
+ * Вибір відбувається за критеріями: менша кількість змінених файлів, менший розмір patch, менша латентність.
+ * @param {CandidateAttempt[]} attempts - Масив усіх спроб (candidates).
+ * @returns {CandidateAttempt|null} Найкращий чистий кандидат, або null, якщо жоден не знайдено.
+ */
+export function chooseCleanCandidate(attempts) {
+  const clean = attempts.filter(a => a.clean)
+  if (clean.length === 0) return null
+  return clean.toSorted((a, b) => {
+    const byTouched = a.touchedFiles.length - b.touchedFiles.length
+    if (byTouched !== 0) return byTouched
+    const byBytes = a.changedBytes - b.changedBytes
+    if (byBytes !== 0) return byBytes
+    const byTime = a.wallMs - b.wallMs
+    if (byTime !== 0) return byTime
+    return a.index - b.index
+  })[0]
+}
+
+/**
+ * Виконує послідовність випробувань (sampling) для одного tier.
+ * Для кожного кандидата виконується rollback до S1, запускається worker,
+ * оцінюється чистота, і якщо кандидат обраний, застосовується його patch.
+ * @param {object} args - Аргументи для експерименту.
+ * @param {import('./types.mjs').LintViolation[]} args.violations - Початкові порушення для перевірки.
+ * @param {object} args.ctx - Базовий контекст для фіксації.
+ * @param {ExperimentRung} args.rung - Конфігурація поточного експерименту.
+ * @param {SamplingCandidate[]} args.candidates - Список кандидатів для тестування.
+ * @param {(violations: import('./types.mjs').LintViolation[], ctx: object) => Promise<{ touchedFiles?: string[], telemetry?: object }|void>} args.worker - Функція для виконання фіксу.
+ * @param {(ctx: object) => Promise<import('./types.mjs').LintViolation[]> | import('./types.mjs').LintViolation[]} args.detect - Функція для перевірки порушень після застосування/умовами.
+ * @param {(attempts: CandidateAttempt[]) => CandidateAttempt|null} [args.choose] - Стратегія вибору найкращого кандидата.
+ * @param {(ctx: object) => Promise<object|null> | object | null} [args.judge] - Функція для відгуку судді (judge).
+ * @param {() => number} [args.clock] - Функція для отримання часу.
+ * @returns {Promise<{ clean: boolean, selected: CandidateAttempt|null, attempts: CandidateAttempt[], finalViolations: import('./types.mjs').LintViolation[], judgeFeedback: object|null }>} Результат виконання експерименту.
+ */
+export async function runTierSamplingExperiment(args) {
+  const choose = args.choose ?? chooseCleanCandidate
+  const clock = args.clock ?? (() => Date.now())
+  const snapshot = createSnapshot()
+  /** @type {CandidateAttempt[]} */
+  const attempts = []
+
+  for (const [index, candidate] of args.candidates.entries()) {
+    snapshot.rollback()
+    const recordedThisCandidate = new Set()
+    const startedAt = clock()
+    let error = null
+    let telemetry
+    /** @type {string[]} */
+    let touchedFiles
+
+    const candidateCtx = {
+      ...args.ctx,
+      tier: args.rung.tier,
+      model: args.rung.model,
+      feedback: args.rung.feedback ? args.ctx.feedback : undefined,
+      samplingProfile: candidate.samplingProfile,
+      candidateId: candidate.id,
+      recordWrite(absPath) {
+        recordedThisCandidate.add(absPath)
+        snapshot.record(absPath)
+      }
+    }
+
+    try {
+      const res = await args.worker(args.violations, candidateCtx)
+      touchedFiles = uniqueStrings(res?.touchedFiles?.length ? res.touchedFiles : [...recordedThisCandidate])
+      telemetry = res?.telemetry
+    } catch (workerError) {
+      error = workerError.message
+      touchedFiles = uniqueStrings([...recordedThisCandidate])
+    }
+
+    const detected = await args.detect({ ...candidateCtx, phase: 'candidate-detect' })
+    const patch = detected.length === 0 && !error ? captureFiles(touchedFiles) : []
+    attempts.push({
+      index,
+      id: candidate.id,
+      samplingProfile: candidate.samplingProfile,
+      tier: args.rung.tier,
+      model: args.rung.model,
+      clean: detected.length === 0 && !error,
+      touchedFiles,
+      changedBytes: patchSize(patch),
+      wallMs: clock() - startedAt,
+      error,
+      violations: detected,
+      telemetry,
+      patch
+    })
+  }
+
+  snapshot.rollback()
+  const selected = choose(attempts)
+  if (!selected) {
+    const judgeFeedback = args.judge ? await args.judge({ ...args.ctx, rung: args.rung, attempts }) : null
+    return { clean: false, selected: null, attempts, finalViolations: attempts.at(-1)?.violations ?? [], judgeFeedback }
+  }
+
+  applyCapturedFiles(selected.patch, snapshot)
+  const finalViolations = await args.detect({
+    ...args.ctx,
+    tier: args.rung.tier,
+    model: args.rung.model,
+    samplingProfile: selected.samplingProfile,
+    candidateId: selected.id,
+    phase: 'final-detect'
+  })
+  if (finalViolations.length > 0) {
+    snapshot.rollback()
+    return { clean: false, selected: null, attempts, finalViolations, judgeFeedback: null }
+  }
+  return { clean: true, selected, attempts, finalViolations, judgeFeedback: null }
+}
+
+/**
+ * Видаляє дублікати з масиву рядків.
+ * @param {string[]} values - Вхідний масив рядків.
+ * @returns {string[]} Масив унікальних рядків.
+ */
+function uniqueStrings(values) {
+  return [...new Set(values.filter(v => typeof v === 'string' && v.length > 0))]
+}
+
+/**
+ * Збирає вміст файлів, зазначених у шляхах.
+ * @param {string[]} paths - Масив абсолютних шляхів до файлів.
+ * @returns {Array<{ absPath: string, exists: boolean, content: string }>} Масив об'єктів з інформацією про файли.
+ */
+function captureFiles(paths) {
+  return paths.map(absPath => ({
+    absPath,
+    exists: existsSync(absPath),
+    content: existsSync(absPath) ? readFileSync(absPath, 'utf8') : ''
+  }))
+}
+
+/**
+ * Застосовує зміни (patch) до робочого дерева через snapshot.
+ * @param {Array<{ absPath: string, exists: boolean, content: string }>} patch - Патч для застосування.
+ * @param {object} snapshot - Об'єкт з функцією для запису змін.
+ */
+function applyCapturedFiles(patch, snapshot) {
+  for (const file of patch) {
+    snapshot.record(file.absPath)
+    if (!file.exists) {
+      rmSync(file.absPath, { force: true })
+      continue
+    }
+    mkdirSync(dirname(file.absPath), { recursive: true })
+    writeFileSync(file.absPath, file.content, 'utf8')
+  }
+}
+
+/**
+ * Обчислює загальний розмір патчу.
+ * @param {Array<{ absPath: string, exists: boolean, content: string }>} patch - Масив файлів патчу.
+ * @returns {number} Загальна кількість байтів.
+ */
+function patchSize(patch) {
+  return patch.reduce((sum, file) => sum + file.content.length, 0)
+}

package/scripts/lib/lint-surface/types.mjs

@@ -0,0 +1,150 @@
+/**
+ * Контракти unified lint surface (spec: docs/specs/2026-06-29-unified-lint-surface.md).
+ *
+ * Один detector API, один result type, дві чесні ролі:
+ *   - `lint(ctx) -> LintResult` тільки виявляє порушення (read-only, без LLM, без side effects);
+ *   - central fix pipeline (T0 + tier ladder) виправляє і перевіряє результат.
+ *
+ * Цей модуль не містить runtime-логіки — лише JSDoc typedefs, спільні для runner-а,
+ * detector-ів, T0-патернів і fix-worker-ів. Імпортуй через `@typedef {import(...)}`.
+ */
+
+/**
+ * Вхід detector-а. Runner будує `ctx` per concern.
+ * @typedef {object} LintContext
+ * @property {string} cwd абсолютний корінь consumer-репо
+ * @property {string} ruleId id правила (`rules/<rule>`)
+ * @property {string} concernId id concern-а (`rules/<rule>/<concern>`)
+ * @property {string} [concernDir] абсолютний шлях до каталогу concern-а (для T0, що читають
+ *   власний `template/`); runner заповнює, detector зазвичай не потребує
+ * @property {string[]} [files] posix-relative файли від `cwd` для per-file запуску;
+ *   `undefined` означає whole-repo
+ * @property {boolean} [verbose] `--verbose` CLI-прапорець; concern-и із зовнішніми
+ *   інструментами (напр. `ga/workflows`) звіряються з ним, щоб не засмічувати прогрес-бар `lint --full`
+ */
+
+/**
+ * Одне порушення. Namespace стабільного коду — `(ruleId, concernId, reason)`,
+ * тому різні concerns можуть мати однакові `reason` (`missing`, `crc-mismatch`, ...).
+ * @typedef {object} LintViolation
+ * @property {string} ruleId заповнюється detector-ом із ctx або normalizer-ом runner-а
+ * @property {string} concernId id concern-а, до якого належить порушення
+ * @property {string} reason стабільний machine code (`crc-mismatch`, `no-unused-vars`)
+ * @property {string} message людиночитний опис (єдине джерело для runner-render)
+ * @property {string} [file] posix-relative шлях від cwd; absolute і `..` заборонені
+ * @property {'error'|'warn'} [severity] default `error`
+ * @property {Record<string, unknown>} [data] concern-specific payload для T0/worker;
+ *   runner не розгалужується за його формою
+ */
+
+/**
+ * Технічна діагностика (не основний violation-report). Runner показує у verbose/debug.
+ * @typedef {object} LintDiagnostic
+ * @property {'info'|'warn'} level рівень діагностики
+ * @property {string} message текст діагностики
+ */
+
+/**
+ * Результат detector-а. Не містить exit code — exit це похідна CLI-семантика
+ * (0 = немає violations, 1 = є, 2 = exception/invalid result/tool crash).
+ * @typedef {object} LintResult
+ * @property {LintViolation[]} violations перелік виявлених порушень
+ * @property {LintDiagnostic[]} [diagnostics] технічні діагностики для verbose/debug
+ */
+
+/**
+ * Detector-контракт concern-а (`main.mjs`).
+ * @callback LintFn
+ * @param {LintContext} ctx
+ * @returns {Promise<LintResult> | LintResult}
+ */
+
+/**
+ * Детермінований T0-патерн (`fix-<concern>.mjs` експортує `patterns: T0Pattern[]`).
+ * Отримує ТІЛЬКИ violations свого concern-а (runner scope-ить за ruleId/concernId).
+ * @typedef {object} T0Pattern
+ * @property {string} id унікальний id патерну (дедуп за ним при re-export)
+ * @property {(violations: LintViolation[]) => boolean} test чи застосовний патерн
+ * @property {(violations: LintViolation[], ctx: LintContext) => Promise<T0Result> | T0Result} apply застосовує детерміноване виправлення й повертає результат
+ * @property {boolean} [standalone] true — патерн сам ідемпотентний і самоаналізуючий (напр.
+ *   `oxfmt --write`, `ruff --fix`): не потребує per-violation даних, щоб вирішити, чи
+ *   запускати `apply()` — runner обходить `test()` і, якщо ВСІ патерни concern-а standalone,
+ *   пропускає початковий detect у fix-режимі (spec
+ *   docs/specs/2026-07-02-text-check-per-file-split-design.md §8, Phase 2). Не стосується
+ *   `--no-fix` (detect-only) шляху.
+ */
+
+/**
+ * @typedef {object} T0Result
+ * @property {string[]} touchedFiles абсолютні шляхи змінених файлів
+ * @property {string} [message] опис дії для debug/telemetry
+ */
+
+/**
+ * Контекст одного rung-а fix-worker-а. Описує single attempt, НЕ всю ladder.
+ * Worker знає поточний tier/model і feedback попереднього rung-а, але не вирішує,
+ * який tier буде наступним, не володіє rollback і не визначає success.
+ * @typedef {object} FixContext
+ * @property {string} cwd абсолютний корінь consumer-репо
+ * @property {string} ruleId id правила поточного concern-а
+ * @property {string} concernId id concern-а, який виправляється
+ * @property {string[]} [files] posix-relative файли для per-file виправлення; `undefined` — whole-repo
+ * @property {'local-min'|'local-min-retry'|'cloud-min'|'cloud-avg'} tier поточний rung ladder-а
+ * @property {string} [model] "provider/model-id"
+ * @property {number} [timeoutMs] per-tier таймаут rung-а (ADR 260620-0556) — worker
+ *   ЗОБОВ'ЯЗАНИЙ прокинути його у свій LLM-виклик (напр. `runAgentFix`/`runOneShot`
+ *   opts.timeoutMs), щоб зависла сесія переривалась зсередини (abort); runner додатково тримає
+ *   backstop ×1.25 навколо всього worker-виклику
+ * @property {AbortSignal} [signal] сигнал скасування rung-а
+ * @property {object} [feedback] structured diagnosis попереднього rung-а
+ * @property {(absPath: string) => void} recordWrite worker ЗОБОВ'ЯЗАНИЙ викликати
+ *   перед будь-яким записом у файл — runner так знімає pre-image для central rollback.
+ *   Це обов'язок реєстрації, НЕ володіння rollback-ом (rollback лишається в runner).
+ * @property {(absPath: string) => void} [recordDurableWrite] durable-реєстрація для
+ *   worker-ів, чиї записи — самодостатні кінцеві стани (файл або записаний повністю й
+ *   валідний, або не записаний; напр. doc-files: кожна дока зі свіжим CRC, degraded теж
+ *   валідна). Durable-файли переживають rollback провального rung-а — прогрес великого
+ *   батчу не стирається, canonical re-detect рахує лише те, що реально лишилось; у
+ *   semantic-collateral veto вони не входять. Для правок наявного стороннього коду —
+ *   ЗАВЖДИ recordWrite (rollback-контракт незмінний).
+ * @property {object} [chain] chain handle concern-а (@7n/llm-lib/chain) — worker
+ *   прокидає його у runAgentFix/runOneShot, щоб рунг став кроком ланцюжка.
+ * @property {(args: { touchedFiles: string[] }) => Promise<{ ok: boolean, output?: string }>} [verify]
+ *   evidence-гейт рунга (дизайн 2026-07-11 Фаза A1): item-scoped canonical re-detect.
+ *   Worker прокидає у `runAgentFix` opts.verify — провал інʼєктиться фідбеком у ту саму
+ *   pi-сесію (до `verifyMax` ітерацій). Це НЕ заміна зовнішнього canonical re-detect
+ *   runner-а (він лишається вердиктом) — лише рання петля всередині рунга.
+ * @property {number} [verifyMax] додаткові verify-ітерації рунга (local — менше, cloud — більше).
+ */
+
+/**
+ * Контракт fix-worker-а (`fix-worker.mjs` експортує `fixWorker`).
+ * Повертає лише застосовані зміни — success визначає canonical re-check runner-а.
+ * @callback FixWorkerFn
+ * @param {LintViolation[]} violations violations свого concern-а
+ * @param {FixContext} ctx
+ * @returns {Promise<FixWorkerResult>}
+ */
+
+/**
+ * @typedef {object} FixWorkerResult
+ * @property {string[]} touchedFiles абсолютні шляхи змінених файлів
+ * @property {object} [telemetry] опційні метрики rung-а
+ */
+
+/**
+ * Поверхня policy-concern-а у concern.json (target-семантика для generated detector-а).
+ * @typedef {object} PolicySurface
+ * @property {'rego'|'template'} engine рушій перевірки policy-concern-а
+ * @property {{ single?: string, walkGlob?: string|string[], required?: boolean }} files цільові файли concern-а (одиничний, glob-обхід, обовʼязковість)
+ * @property {string} [missingMessage] override fail-повідомлення для required:single
+ */
+
+/**
+ * Lint-поверхня concern-а (коли concern запускається).
+ * @typedef {object} LintSurface
+ * @property {'per-file'|'full'} scope режим запуску concern-а (пофайлово чи по всьому дереву)
+ * @property {string[]} glob нормалізований масив; порожній якщо не задано
+ */
+
+export {}

package/scripts/lib/lint-surface/violation-reporter.mjs

@@ -0,0 +1,46 @@
+/**
+ * Drop-in заміна `createCheckReporter` для міграції check-concern-ів у detector-и.
+ *
+ * Старий reporter друкував pass/fail і накопичував exit code. Detector НЕ друкує —
+ * цей reporter накопичує `LintViolation[]`. Тіло concern-а майже не змінюється:
+ *   - `createCheckReporter()` → `createViolationReporter(ctx)`
+ *   - `return reporter.getExitCode()` → `return reporter.result()`
+ *
+ * `fail(msg)` за замовчуванням дає `reason = ctx.concernId`. Для кількох типів порушень
+ * у одному concern-і — `fail(msg, 'specific-reason')` або `fail(msg, { reason, file, data })`.
+ * @typedef {import('./types.mjs').LintContext} LintContext
+ * @typedef {import('./types.mjs').LintViolation} LintViolation
+ * @typedef {import('./types.mjs').LintResult} LintResult
+ */
+
+/**
+ * @param {LintContext} ctx контекст concern-а (джерело дефолтного reason).
+ * @returns {{
+ *   pass: (...args: unknown[]) => void,
+ *   fail: (msg: string, opts?: string | { reason?: string, file?: string, severity?: 'error'|'warn', data?: object }) => void,
+ *   result: () => LintResult
+ * }} reporter, що накопичує порушення й повертає LintResult.
+ */
+export function createViolationReporter(ctx) {
+  /** @type {LintViolation[]} */
+  const violations = []
+  const defaultReason = ctx?.concernId ?? 'violation'
+  return {
+    // detector не друкує — pass стає no-op (успіхи рендерить runner відсутністю violations)
+    pass() {
+      // навмисний no-op: успіх не накопичує violation
+    },
+    fail(msg, opts) {
+      const o = typeof opts === 'string' ? { reason: opts } : (opts ?? {})
+      /** @type {Record<string, unknown>} */
+      const v = { reason: o.reason ?? defaultReason, message: msg }
+      if (o.file) v.file = o.file
+      if (o.severity) v.severity = o.severity
+      if (o.data) v.data = o.data
+      violations.push(/** @type {LintViolation} */ (v))
+    },
+    result() {
+      return { violations }
+    }
+  }
+}

package/scripts/lib/list-project-rules-mdc.mjs

@@ -0,0 +1,22 @@
+/**
+ * Список `.mdc`-файлів правил у `.cursor/rules/` проєкту-споживача (відсортований).
+ * Винесено зі `bin/n-rules.js`, щоб ділити між CLI-dispatch і `run-conformance-check` (конформність-детект).
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+import { globby } from 'globby'
+
+/** Каталог правил у проєкті-споживачі (відносно кореня). */
+export const CURSOR_RULES_DIR = '.cursor/rules'
+
+/**
+ * @param {string} [cwd] корінь проєкту
+ * @returns {Promise<string[]>} імена `*.mdc` (відсортовані), або `[]` якщо каталогу немає
+ */
+export async function listProjectRulesMdcFiles(cwd = processCwd()) {
+  const dir = join(cwd, CURSOR_RULES_DIR)
+  if (!existsSync(dir)) return []
+  const names = await globby('*.mdc', { cwd: dir, onlyFiles: true, gitignore: false })
+  return names.toSorted((a, b) => a.localeCompare(b))
+}

package/scripts/lib/list-rule-ids.mjs

@@ -0,0 +1,32 @@
+/**
+ * Перебір `rules/<id>/` директорій з фільтром на наявність entrypoint-а.
+ * Канон (ADR 2026-06-21): єдиний entrypoint `rules/<id>/main.mjs`. Каталог без нього —
+ * пропускається (це not-a-rule або заглушка).
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * Чи має каталог правила entrypoint `main.mjs`.
+ * @param {string} ruleDir абсолютний шлях `rules/<id>/`
+ * @returns {boolean} true, якщо `main.mjs` існує
+ */
+function hasEntrypoint(ruleDir) {
+  return existsSync(join(ruleDir, 'main.mjs'))
+}
+
+/**
+ * @param {string} bundledRulesDir абсолютний шлях до `npm/rules/`
+ * @param {string} [filter] id одного правила (через `--rule abie`)
+ * @returns {Promise<string[]>} відсортовані алфавітно id
+ */
+export async function listRuleIds(bundledRulesDir, filter) {
+  const entries = await readdir(bundledRulesDir, { withFileTypes: true })
+  const ids = entries
+    .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+    .map(e => e.name)
+    .filter(id => hasEntrypoint(join(bundledRulesDir, id)))
+    .filter(id => filter === undefined || id === filter)
+  return ids.toSorted((a, b) => a.localeCompare(b))
+}

package/scripts/lib/load-cursor-config.mjs

@@ -0,0 +1,58 @@
+/**
+ * Утиліта читання `.n-rules.json` у корені репозиторію (fallback — legacy `.n-cursor.json`
+ * до першого синку, який мігрує ім'я файлу).
+ *
+ * Зараз експортує `loadCursorIgnorePaths(root)` — список абсолютних posix-шляхів каталогів,
+ * які check-скрипти повністю виключають з обходу (поле `ignore` у конфізі).
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { isAbsolute, join, resolve, sep } from 'node:path'
+
+const CONFIG_FILE = '.n-rules.json'
+const LEGACY_CONFIG_FILE = '.n-cursor.json'
+
+/**
+ * Нормалізує шлях до абсолютного posix-формату без trailing-slash.
+ * Відносні шляхи розв'язуються від `root`.
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {string} p шлях з конфігу (відносний або абсолютний)
+ * @returns {string} абсолютний posix-шлях
+ */
+function toAbsPosix(root, p) {
+  const trimmed = String(p).trim()
+  const abs = isAbsolute(trimmed) ? trimmed : resolve(root, trimmed)
+  let posix = abs.split(sep).join('/')
+  while (posix.endsWith('/')) posix = posix.slice(0, -1)
+  return posix
+}
+
+/**
+ * Читає `.n-rules.json` з кореня та повертає нормалізовані ignore-шляхи.
+ * Якщо файлу нема, поле `ignore` відсутнє чи має невалідний формат — повертає порожній масив.
+ * Сам конфіг не валідується (це робить v8r/окрема перевірка) — лише поле `ignore`.
+ * @param {string} root абсолютний корінь репозиторію
+ * @returns {Promise<string[]>} абсолютні posix-шляхи без trailing-slash
+ */
+export async function loadCursorIgnorePaths(root) {
+  let file = join(root, CONFIG_FILE)
+  if (!existsSync(file)) file = join(root, LEGACY_CONFIG_FILE)
+  if (!existsSync(file)) return []
+  let raw
+  try {
+    raw = JSON.parse(await readFile(file, 'utf8'))
+  } catch {
+    return []
+  }
+  const list = raw?.ignore
+  if (!Array.isArray(list)) return []
+  /** @type {string[]} */
+  const out = []
+  for (const item of list) {
+    if (typeof item !== 'string') continue
+    const v = item.trim()
+    if (v.length === 0) continue
+    out.push(toAbsPosix(root, v))
+  }
+  return out
+}

package/scripts/lib/mirror-parity.mjs

@@ -0,0 +1,62 @@
+/**
+ * Parity дзеркала правил: `.cursor/rules/n-<id>.mdc` має дорівнювати канонічному
+ * `npm/rules/<id>/<id>.mdc` з inlined-шаблонами — тим самим трансформом, що його
+ * застосовує синк (`readBundledRuleContent` → `inlineTemplateLinks`). Дрейф виникає,
+ * коли канонічний `.mdc` змінюють, не регенерувавши дзеркало (беклог адаптації flow #10).
+ *
+ * Використовується і тестом-гардом (drift === []), і разовою регенерацією.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { appendDiscoveredMdcFiles, inlineTemplateLinks } from './inline-template-links.mjs'
+
+const MIRROR_PREFIX = 'n-'
+const MDC_EXT = '.mdc'
+
+/**
+ * Керовані дзеркала `.cursor/rules/n-<id>.mdc`, що мають канонічне джерело
+ * `npm/rules/<id>/<id>.mdc`. Дзеркала без канону (зовнішні) пропускаються.
+ * @param {string} repoRoot корінь репо
+ * @returns {{ id: string, mirrorPath: string, canonicalPath: string }[]} список
+ */
+export function listManagedMirrors(repoRoot) {
+  const rulesDir = join(repoRoot, '.cursor/rules')
+  if (!existsSync(rulesDir)) return []
+  return readdirSync(rulesDir)
+    .filter(f => f.startsWith(MIRROR_PREFIX) && f.endsWith(MDC_EXT))
+    .map(f => {
+      const id = f.slice(MIRROR_PREFIX.length, -MDC_EXT.length)
+      return {
+        id,
+        mirrorPath: join(rulesDir, f),
+        canonicalPath: join(repoRoot, 'npm/rules', id, `main${MDC_EXT}`)
+      }
+    })
+    .filter(m => existsSync(m.canonicalPath))
+}
+
+/**
+ * Очікуваний вміст дзеркала = канон з inlined-шаблонами (трансформ синку).
+ * @param {string} canonicalPath абсолютний шлях `npm/rules/<id>/<id>.mdc`
+ * @returns {Promise<string>} очікуваний текст дзеркала
+ */
+export async function expectedMirrorContent(canonicalPath) {
+  const dir = dirname(canonicalPath)
+  const withTemplates = await inlineTemplateLinks(readFileSync(canonicalPath, 'utf8'), dir)
+  return appendDiscoveredMdcFiles(withTemplates, dir)
+}
+
+/**
+ * Id дзеркал, що розійшлися з каноном (actual ≠ expected).
+ * @param {string} repoRoot корінь репо
+ * @returns {Promise<string[]>} відсортовані id дрейфу
+ */
+export async function findMirrorDrift(repoRoot) {
+  const drift = []
+  for (const m of listManagedMirrors(repoRoot)) {
+    const expected = await expectedMirrorContent(m.canonicalPath)
+    if (readFileSync(m.mirrorPath, 'utf8') !== expected) drift.push(m.id)
+  }
+  return drift.toSorted()
+}