@nitra/cursor 11.4.1 → 12.0.0

package/scripts/lib/adr/docs/normalize-cli.md

@@ -1,15 +1,13 @@
 ---
+type: JS Module
+title: normalize-cli.mjs
+resource: npm/scripts/lib/adr/normalize-cli.mjs
 docgen:
-  source: normalize-cli.mjs
   crc: ce2f13af
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 90
 ---
 
-# normalize-cli.mjs
-
-## Огляд
-
 Цей файл є CLI-обгорткою для локального ADR-нормалізатора (`n-cursor adr-normalize-local`). Він використовується скриптом `.claude/hooks/normalize-decisions.sh` як локальний бекенд для обробки батчу чернеток та списку чистих ADR. Обгортка зчитує шляхи до чернеток та параметри з аргументів командного рядка та змінних середовища, а потім проганяє `normalizePipeline`. Результатом роботи є вивід JSON-контракту з операціями у stdout, який парситься зовнішнім скриптом. Прогрес відображається у stderr.
 
 ## Поведінка

package/scripts/lib/adr/docs/normalize-pipeline.md

@@ -1,15 +1,13 @@
 ---
+type: JS Module
+title: normalize-pipeline.mjs
+resource: npm/scripts/lib/adr/normalize-pipeline.mjs
 docgen:
-  source: normalize-pipeline.mjs
-  crc: 6619ff48
+  crc: 6eb6ba69
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-# normalize-pipeline.mjs
-
-## Огляд
-
 Файл реалізує локально-орієнтований конвеєр для нормалізації чернеток ADR. Він використовує LLM лише для вузьких, верифікованих бінарних суджень. Конвеєр працює у послідовних стадіях: JS виконує пошук кандидатів-ребер на основі лексичної схожості, LLM оцінює ці ребра (Stage 1: `same/different`) та драфти (Stage 1b: `standalone/trivial`), JS кластеризує підтверджені ребра (використовуючи `union-find`), LLM реформатує анотера (Stage 2: `gen-MADR`), а LLM генерує доповнення для злиття (Stage 3: `gen-merge`). Глобальний стан (кластери, слаги, покриття) зберігається в JS. Конвеєр повертає операції у форматі `operations[]`, сумісного з контрактом `apply-ops`.
 
 ## Поведінка

package/scripts/lib/adr/normalize-pipeline.mjs

@@ -3,20 +3,22 @@
  * LLM відповідає лише на вузькі verifiable-питання). Альтернатива single-shot-у
  * normalize-decisions.sh, заточена під малу локальну модель (omlx/gemma-4b).
  *
- * Принцип: модель НІКОЛИ не приймає глобальних рішень і не повертає великих
- * структур. Глобальний стан (кластери, слаги, покриття) тримає JS. Модель:
+ * Принцип: модель НІКОЛИ не приймає глобальних рішень, не повертає великих
+ * структур і НЕ форматує. Глобальний стан (кластери, слаги, покриття) та весь
+ * MADR-каркас (заголовок, Status/Date, назви секцій, fallback-фрази, шаблон
+ * "Chosen option…") тримає JS. Модель повертає лише вузький, verifiable зміст:
  *   - судить пару записів бінарно «те саме рішення? так/ні» (Stage 1),
  *   - для ізольованого драфта каже standalone/trivial (Stage 1b),
- *   - реформатить один драфт у чистий MADR (Stage 2),
- *   - пише short merge-additions (Stage 3).
+ *   - витягує зміст секцій одного драфта як JSON (Stage 2) — каркас будує JS,
+ *   - пише short merge-additions без заголовка (Stage 3) — «## Update <date>» додає JS.
  *
  * Стадії:
  *   0. retrieval (JS)   — лексична схожість → кандидати-ребра draft↔draft / draft↔clean
  *   1. edge-judge (LLM) — бінарне same/different по кожному ребру (self-consistency)
  *   1b. kind-judge(LLM) — standalone vs trivial для драфтів без ребер
  *   ── cluster (JS)     — union-find по підтверджених ребрах, вибір anchor, призначення op
- *   2. gen-MADR (LLM)   — reformat anchor/standalone → чистий MADR + validation gate
- *   3. gen-merge (LLM)  — additions для merge-драфтів
+ *   2. gen-MADR         — LLM витягує секції-JSON → assembleMadr() (JS) збирає канон → validation gate
+ *   3. gen-merge        — LLM пише additions-прозу → JS додає «## Update <date>»-заголовок
  *   ── assemble (JS)    — operations[] у форматі, сумісному з apply-ops
  *
  * Повертає той самий operations[]-контракт, що й single-shot — apply-логіка спільна.
@@ -38,6 +40,7 @@ const RE_SLUG_NONWORD = /[^a-zа-яіїєґ0-9]+/gi
 const RE_LEAD_HYPHEN = /^-+/
 const RE_TRAIL_HYPHEN = /-+$/
 const RE_UPDATE_HEAD = /^##\s+Update/
+const RE_UPDATE_HEAD_LINE = /^##\s+Update[^\n]*\n+/
 const RE_DECISION_SECTION = /##\s*Decision Outcome\s*([\s\S]{0,500})/i
 const RE_NO_DECISION = /(не\s+обрано|не\s+прийнят|рішення\s+не\s+прийн|не\s+зроблен|no\s+decision|undecided)/i
 const RE_FENCE_LEAD = /^\s*```/
@@ -300,79 +303,170 @@ export function validateMadr(content) {
   const errors = []
   if (!content || content.length < 80) errors.push('too short')
   if (RE_FENCE_LEAD.test(content) || RE_FENCE_TRAIL.test(content.trim())) errors.push('code-fence wrapper')
-  if (RE_FRONTMATTER.test(content.split('\n').slice(0, 3).join('\n'))) errors.push('has YAML frontmatter')
+  // OKF conformance: must have YAML frontmatter with type: ADR (not draft session: fields)
+  const fmMatch = /^---\n([\s\S]*?)\n---/.exec(content)
+  if (!fmMatch || !/^type:\s*ADR\s*$/m.test(fmMatch[1])) errors.push('missing OKF type: ADR frontmatter')
   if (RE_SESSION.test(content)) errors.push('leaked session: field')
-  if (!RE_H1.test(content)) errors.push('missing # title')
   if (!RE_STATUS.test(content)) errors.push('missing Status')
   if (!RE_DATE.test(content)) errors.push('missing/!ISO Date')
   for (const h of MADR_HEADINGS) if (!content.includes(h)) errors.push(`missing heading ${h}`)
   return { ok: errors.length === 0, errors }
 }
 
-const GEN_SYS = `Ти нормалізуєш чернетку ADR у чистий фінальний MADR 4.0.0. Чернетка вже містить секції — твоя задача ОЧИСТИТИ й привести до канону, НЕ вигадуючи нового.
-
-Поверни ЛИШЕ markdown файлу (починається з "# "), без code-fence, без передмови, без YAML frontmatter.
-
-Структура РІВНО така:
-# <Заголовок українською>
+// Інверсія форматування: модель НЕ генерує markdown-каркас MADR (заголовок,
+// Status/Date, назви секцій, fallback-фрази, шаблон "Chosen option…") — усе це
+// детерміновано, тому його будує JS у assembleMadr(). Модель повертає ЛИШЕ
+// контент секцій як вузький JSON — те, що справді треба "витягти" з чернетки.
+// Контракт: модель віддає ЛИШЕ зміст секцій (значення полів — markdown-проза зі
+// збереженим inline-кодом). Каркас (заголовок, Status/Date, назви секцій ##,
+// fallback-фрази, шаблон "Chosen option…") будує assembleMadr() детерміновано —
+// тому модель НЕ пише жодних ## і не торкається заголовка/дати/статусу.
+const GEN_SYS = `Ти витягуєш зміст архітектурного рішення з чернетки ADR у JSON. Нічого не вигадуй — бери лише те, що є в чернетці.
+
+{
+  "context": "<2-4 речення: проблема й контекст рішення>",
+  "options": ["<розглянутий варіант>", "..."],
+  "chosen": "<обраний варіант, коротко>",
+  "rationale": "<чому обрано саме його>",
+  "good": ["<позитивний наслідок>", "..."],
+  "bad": ["<негативний наслідок>", "..."],
+  "more": "<файли/команди/API; можна кілька рядків і bullets>"
+}
 
-**Status:** Accepted
-**Date:** <YYYY-MM-DD з поля captured чернетки, перші 10 символів>
+ВАЖЛИВО про значення полів:
+- Зберігай inline-форматування: backticks навколо \`шляхів\`, \`назв.функцій()\`, \`команд\` — це частина змісту, не прибирай їх.
+- НЕ додавай markdown-ЗАГОЛОВКИ (рядки з ##) і не пиши сам каркас (Status, Date, назви секцій) — лише зміст.
+- Якщо чогось нема в чернетці — порожній рядок "" або порожній масив [].
 
-## Context and Problem Statement
-<...>
+Поверни ЛИШЕ JSON, без code-fence, без передмови.`
 
-## Considered Options
-<bullets; якщо альтернатив не було — "Інші варіанти не обговорювалися.">
+const slugify = (title) =>
+  title.toLowerCase().replace(RE_SLUG_NONWORD, '-').replace(RE_LEAD_HYPHEN, '').slice(0, 60).replace(RE_TRAIL_HYPHEN, '') || 'adr'
 
-## Decision Outcome
-Chosen option: "<...>", because <...>.
+const RE_FNAME_DATE = /^(\d{2})(\d{2})(\d{2})-/
+const RE_TRAIL_DOT = /\.+\s*$/
 
-### Consequences
-<bullets "Good, because ...", "Bad, because ...">
+/**
+ * Детермінована ISO-дата для поля **Date:**. Пріоритет — `captured` frontmatter
+ * (перші 10 символів ISO-стемпа); fallback — timestamp-префікс імені файлу
+ * (`YYMMDD-…` → `20YY-MM-DD`). Каркас MADR не повинен залежати від LLM навіть тут.
+ * @param {string|undefined} captured значення поля captured (ISO-рядок)
+ * @param {string} [file] basename чернетки (для fallback-дати)
+ * @returns {string} ISO-дата `YYYY-MM-DD` або '' якщо нічого не вдалося витягти
+ */
+export function madrDate(captured, file = '') {
+  const iso = (captured ?? '').slice(0, 10)
+  if (RE_DATE.test(`**Date:** ${iso}`)) return iso
+  const m = file.match(RE_FNAME_DATE)
+  return m ? `20${m[1]}-${m[2]}-${m[3]}` : ''
+}
 
-## More Information
-<файли, команди, API; якщо нема — "Додаткової інформації не зафіксовано.">
+const secStr = (v) => (typeof v === 'string' ? v.trim() : v === null || v === undefined ? '' : String(v).trim())
+const secArr = (v) => (Array.isArray(v) ? v.map(secStr).filter(Boolean) : secStr(v) ? [secStr(v)] : [])
 
-Не вигадуй альтернатив, наслідків чи контексту, яких нема в чернетці. Прибери YAML frontmatter (session/captured/transcript) повністю.`
+/**
+ * Нормалізує сирий JSON-вивід gen-моделі у строгу форму секцій. Толерантна до
+ * дрібних відхилень малої моделі: рядок замість масиву → масив із одного елемента,
+ * число/null → рядок/порожньо, обрізає пробіли й порожні елементи.
+ * @param {any} obj розпарсений JSON-обʼєкт від моделі
+ * @returns {{context:string, options:string[], chosen:string, rationale:string, good:string[], bad:string[], more:string}} нормалізовані секції
+ */
+export function normalizeSections(obj) {
+  return {
+    context: secStr(obj?.context),
+    options: secArr(obj?.options),
+    chosen: secStr(obj?.chosen),
+    rationale: secStr(obj?.rationale),
+    good: secArr(obj?.good),
+    bad: secArr(obj?.bad),
+    more: secStr(obj?.more)
+  }
+}
 
-const slugify = (title) =>
-  title.toLowerCase().replace(RE_SLUG_NONWORD, '-').replace(RE_LEAD_HYPHEN, '').slice(0, 60).replace(RE_TRAIL_HYPHEN, '') || 'adr'
+/**
+ * Детермінована збірка канонічного MADR 4.0.0 з заголовка, дати й секцій-контенту.
+ * Увесь каркас (Status, назви секцій, шаблон "Chosen option…", fallback-фрази,
+ * bullets) — тут, не в моделі. Заголовок і дата — JS-власність (draftTitle/captured),
+ * модель їх не торкається.
+ * @param {{title:string, date:string, sections:ReturnType<typeof normalizeSections>}} input заголовок, ISO-дата, нормалізовані секції
+ * @returns {string} готовий MADR-markdown
+ */
+export function assembleMadr({ title, date, sections: s }) {
+  // Знімаємо кінцеву крапку контенту, бо шаблон додає свою (інакше "..").
+  const noDot = (x) => x.replace(RE_TRAIL_DOT, '')
+  const optBlock = s.options.length ? s.options.map((o) => `* ${o}`).join('\n') : 'Інші варіанти не обговорювалися.'
+  const cons = [...s.good.map((g) => `* Good, because ${noDot(g)}.`), ...s.bad.map((b) => `* Bad, because ${noDot(b)}.`)]
+  const consBlock = cons.length ? cons.join('\n') : 'Підтверджених наслідків не зафіксовано.'
+  const outcome = s.chosen
+    ? `Chosen option: "${s.chosen}"${s.rationale ? `, because ${noDot(s.rationale)}` : ''}.`
+    : s.rationale ? `${noDot(s.rationale)}.` : 'Рішення зафіксовано у чернетці.'
+  return [
+    `# ${title}`,
+    '',
+    '**Status:** Accepted',
+    `**Date:** ${date}`,
+    '',
+    '## Context and Problem Statement',
+    s.context || 'Контекст не зафіксовано у чернетці.',
+    '',
+    '## Considered Options',
+    optBlock,
+    '',
+    '## Decision Outcome',
+    outcome,
+    '',
+    '### Consequences',
+    consBlock,
+    '',
+    '## More Information',
+    s.more || 'Додаткової інформації не зафіксовано.',
+    ''
+  ].join('\n')
+}
 
-function genMadr(title, body, captured, cfg) {
-  const date = (captured ?? '').slice(0, 10)
-  const user = `Чернетка "${title}" (captured: ${captured ?? 'невідомо'}):\n\n${body}\n\nПоверни чистий MADR. Date = ${date || 'візьми з captured'}.`
+export function genMadr(title, body, captured, cfg, file = '') {
+  const date = madrDate(captured, file)
+  const slug = slugify(title)
+  const user = `Чернетка "${title}":\n\n${body.slice(0, 4000)}\n\nВитягни зміст рішення у JSON.`
   const parse = (raw) => {
-    const content = stripFence(raw)
+    const sections = normalizeSections(extractJson(raw))
+    if (!sections.context && !sections.chosen && !sections.rationale) throw new Error('empty extraction (no context/decision)')
+    const content = assembleMadr({ title, date, sections })
     const v = validateMadr(content)
     if (!v.ok) throw new Error(`MADR invalid: ${v.errors.join('; ')}`)
     return content
   }
   try {
-    const content = callWithCascade([{ role: 'system', content: GEN_SYS }, { role: 'user', content: user }], parse, { label: 'gen', allowCloud: cfg.allowCloud, stats: cfg.stats, attempts: 3, maxTokens: 4096 })
-    return { content, slug: slugify(title), valid: true }
+    const content = callWithCascade([{ role: 'system', content: GEN_SYS }, { role: 'user', content: user }], parse, { label: 'gen', allowCloud: cfg.allowCloud, stats: cfg.stats, attempts: 3, maxTokens: 2048 })
+    return { content, slug, valid: true }
   } catch (error) {
     cfg.stats.madrInvalid++
-    return { content: null, slug: slugify(title), valid: false, error: error.message }
+    return { content: null, slug, valid: false, error: error.message }
   }
 }
 
 // ─────────────────────────── Stage 3: gen-merge (LLM) ──────────────────────────
 
-const MERGE_SYS = `Ти готуєш короткий блок-доповнення до існуючого ADR. Поверни ЛИШЕ markdown-блок (без code-fence), що починається рядком "## Update <YYYY-MM-DD>", і містить ЛИШЕ новий зміст, якого ще нема в цільовому ADR (уточнення/виправлення/продовження). Стисло. Без передмови.`
+// Каркас merge-блоку («## Update <date>») — теж JS-власність. Модель пише ЛИШЕ
+// новий зміст-прозу; заголовок із детермінованою датою додає genMerge.
+const MERGE_SYS = `Ти готуєш короткий додаток до існуючого ADR. Напиши ЛИШЕ новий зміст (проза/bullets), якого ще НЕМА в цільовому ADR — уточнення/виправлення/продовження. Стисло, українською, без заголовків, без code-fence, без передмови.`
 
-function genMerge(title, body, captured, targetTitle, cfg) {
-  const date = (captured ?? '').slice(0, 10)
-  const user = `Цільовий ADR: "${targetTitle}".\nЧернетка-доповнення "${title}" (${date}):\n${body.slice(0, 2500)}\n\nДай блок "## Update ${date}" з НОВИМ змістом.`
+function genMerge(title, body, captured, targetTitle, cfg, file = '') {
+  const date = madrDate(captured, file)
+  const user = `Цільовий ADR: "${targetTitle}".\nЧернетка-доповнення "${title}" (${date}):\n${body.slice(0, 2500)}\n\nЛише новий зміст, без заголовка.`
+  const head = `## Update ${date}`
   const parse = (raw) => {
     const t = stripFence(raw)
-    if (!RE_UPDATE_HEAD.test(t)) throw new Error('missing ## Update heading')
-    return t
+    // Захист від моделі, що все одно вписала свій заголовок: знімаємо його, щоб
+    // не подвоїти. Канонічний head додаємо детерміновано нижче.
+    const cleaned = RE_UPDATE_HEAD.test(t) ? t.replace(RE_UPDATE_HEAD_LINE, '').trim() : t
+    if (!cleaned) throw new Error('empty merge additions')
+    return `${head}\n\n${cleaned}`
   }
   try {
     return callWithCascade([{ role: 'system', content: MERGE_SYS }, { role: 'user', content: user }], parse, { label: 'merge', allowCloud: cfg.allowCloud, stats: cfg.stats, attempts: 2, maxTokens: 1500 })
   } catch {
-    return `## Update ${date}\n\n(доповнення з чернетки "${title}")`
+    return `${head}\n\n(доповнення з чернетки "${title}")`
   }
 }
 
@@ -493,7 +587,7 @@ export function normalizePipeline(drafts, cleanList, opts = {}) {
   const slugByIdx = Array.from({ length: drafts.length }).fill(null)
   for (let i = 0; i < drafts.length; i++) {
     if (decision[i].op !== 'rewrite') continue
-    const g = genMadr(titles[i], drafts[i].body, captured[i], cfg)
+    const g = genMadr(titles[i], drafts[i].body, captured[i], cfg, drafts[i].file)
     slugByIdx[i] = g.slug
     if (g.valid) {
       operations.push({ op: 'rewrite', file: drafts[i].file, slug: g.slug, content: g.content })
@@ -509,11 +603,11 @@ export function normalizePipeline(drafts, cleanList, opts = {}) {
     if (d.op === 'merge-anchor') {
       const slug = slugByIdx[d.anchorIdx]
       if (!slug) { log(`merge-anchor ${drafts[i].file}: anchor gen failed → skip`); continue }
-      const add = genMerge(titles[i], drafts[i].body, captured[i], titles[d.anchorIdx], cfg)
+      const add = genMerge(titles[i], drafts[i].body, captured[i], titles[d.anchorIdx], cfg, drafts[i].file)
       operations.push({ op: 'merge-into', file: drafts[i].file, target: `${slug}.md`, additions: add })
     } else if (d.op === 'merge-existing') {
       const cTitle = stripAdrName(d.target)
-      const add = genMerge(titles[i], drafts[i].body, captured[i], cTitle, cfg)
+      const add = genMerge(titles[i], drafts[i].body, captured[i], cTitle, cfg, drafts[i].file)
       operations.push({ op: 'merge-into', file: drafts[i].file, target: d.target, additions: add })
     } else if (d.op === 'delete') {
       operations.push({ op: 'delete', file: drafts[i].file, reason: d.reason })

package/scripts/lib/docs/assert-project-root.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: assert-project-root.mjs
+resource: npm/scripts/lib/assert-project-root.mjs
 docgen:
-  source: npm/scripts/lib/assert-project-root.mjs
   crc: adb87c16
   score: 100
 ---
 
-# assert-project-root.mjs
-
-## Огляд
-
 Файл перевіряє розташування поточного каталогу відносно кореня git-репозиторію. Функції надають доступ до шляху кореня репозиторію та перевірку, чи знаходиться поточний каталог саме в цьому корені. Код спирається на конфіги, визначені у `.n-cursor.json`.
 
 ## Поведінка

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

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: changed-files.mjs
+resource: npm/scripts/lib/changed-files.mjs
 docgen:
-  source: npm/scripts/lib/changed-files.mjs
   crc: 8148d84e
   score: 100
 ---
 
-# changed-files.mjs
-
-## Огляд
-
 Файл збирає змінені та незакомічені файли з робочого дерева. Визначає базовий комміт для перевірок у межах зміненого діапазону. Збирає змінені та незакомічені файли відносно базового комміту.
 
 ## Поведінка

package/scripts/lib/docs/check-mdc-template-refs.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: check-mdc-template-refs.mjs
+resource: npm/scripts/lib/check-mdc-template-refs.mjs
 docgen:
-  source: npm/scripts/lib/check-mdc-template-refs.mjs
   crc: 17b81322
 ---
 
-# check-mdc-template-refs.mjs
-
-## Огляд
-
 Модуль `check-mdc-template-refs.mjs` — це невелика утиліта, призначена для перевірки цілісності посилань між файлом правила `<id>.mdc` та шаблонами, що лежать у підкаталогах `template/` цього самого правила. Він обходить структуру каталогів правила (`fix/<concern>/template/`, `policy/<concern>/template/`), збирає всі знайдені файли й порівнює їхні відносні шляхи з вмістом основного файлу правила `<id>.mdc`. Результатом є перелік шаблонних файлів, на які у `.mdc` немає жодного markdown-посилання, тобто «осиротілі» (orphaned) шаблони.
 
 Типовий контекст застосування: модуль використовується в утилітах перевірки/лінтингу правил репозиторію (`npm/rules/<id>/`), де `.mdc`-файл описує правило людською мовою й має посилатися на свої шаблони. Якщо шаблон існує, але не згаданий у `.mdc`, цей модуль повідомить про нього, щоб супровідник правила або додав посилання, або видалив зайвий шаблон.

package/scripts/lib/docs/check-reporter.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: check-reporter.mjs
+resource: npm/scripts/lib/check-reporter.mjs
 docgen:
-  source: npm/scripts/lib/check-reporter.mjs
   crc: b76ed480
 ---
 
-# check-reporter.mjs
-
-## Огляд
-
 Модуль `check-reporter.mjs` — це невелика спільна (shared) бібліотека-фабрика для check-скриптів (`check-*.mjs`) і для `lint-docker`. Вона надає уніфікований спосіб репортити результати перевірок: успіхи (`pass`) та помилки (`fail`), а також акумулювати фінальний код виходу процесу (`exit code`).
 
 Основна ідея: викликаючи фабрику `createCheckReporter()`, споживач отримує об’єкт з трьома методами — `pass`, `fail` і `getExitCode`. Будь-який виклик `fail` переводить внутрішній лічильник у стан помилки (`exitCode = 1`), і подальший `getExitCode()` повертатиме `1`. Якщо `fail` жодного разу не викликали — `getExitCode()` поверне `0`.

package/scripts/lib/docs/diff-added-lines.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: diff-added-lines.mjs
+resource: npm/scripts/lib/diff-added-lines.mjs
 docgen:
-  source: npm/scripts/lib/diff-added-lines.mjs
   crc: 161edaca
 ---
 
-# diff-added-lines.mjs
-
-## Огляд
-
 Файл визначає, чи є рядок коду новим (introduced) або вже існував у проєкті. Він використовується для класифікації результатів аналізу коду (lint-findings) на основі їхнього розташування відносно версії проєкту. Це допомагає розробникам розуміти, які зміни коду потребують негайної уваги.
 
 ## Поведінка

package/scripts/lib/docs/discover-check-rules-from-cursor.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: discover-check-rules-from-cursor.mjs
+resource: npm/scripts/lib/discover-check-rules-from-cursor.mjs
 docgen:
-  source: npm/scripts/lib/discover-check-rules-from-cursor.mjs
   crc: 9a6916e1
   score: 100
 ---
 
-# discover-check-rules-from-cursor.mjs
-
-## Огляд
-
 Файл зчитує базові імена файлів `.mdc` у директорії `.cursor/rules/` та генерує список ідентифікаторів правил для `npx @nitra/cursor fix`, використовуючи перевірку через JS-концерн або policy з `target.json`.
 
 ## Поведінка

package/scripts/lib/docs/discover-checkable-rules.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: discover-checkable-rules.mjs
+resource: npm/scripts/lib/discover-checkable-rules.mjs
 docgen:
-  source: npm/scripts/lib/discover-checkable-rules.mjs
   crc: 39016d17
 ---
 
-# discover-checkable-rules.mjs
-
-## Огляд
-
 Модуль `discover-checkable-rules.mjs` — це discovery-шар для CLI-команди `fix`. Його завдання — швидко просканувати файлову структуру каталогу `npm/rules/` та виявити «прогонні» правила, тобто правила, у яких є щонайменше один JS-концерн або policy-концерн. Правила, які складаються тільки з декларативних артефактів (`.mdc` + `auto.md`) без жодного прогонного концерну, відсіюються.
 
 Виокремлюються два типи концернів:

package/scripts/lib/docs/ensure-tool.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: ensure-tool.mjs
+resource: npm/scripts/lib/ensure-tool.mjs
 docgen:
-  source: npm/scripts/lib/ensure-tool.mjs
   crc: 230254b3
 ---
 
-# ensure-tool.mjs
-
-## Огляд
-
 Модуль `ensure-tool.mjs` — єдина точка резолву зовнішніх CLI-залежностей пакета `@nitra/cursor`. Він гарантує, що потрібний бінарник (`hk`, `conftest`, `shellcheck`, `actionlint`, `dotenv-linter`, `opa`, `regal`, `hadolint`, `kubeconform`, `kubescape`) доступний у системі, виконуючи послідовний пошук:
 
 1. У системному `PATH` (через `resolveCmd`).

package/scripts/lib/docs/generated-markdown.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: generated-markdown.mjs
+resource: npm/scripts/lib/generated-markdown.mjs
 docgen:
-  source: npm/scripts/lib/generated-markdown.mjs
   crc: 14b85a57
 ---
 
-# generated-markdown.mjs
-
-## Огляд
-
 Модуль `generated-markdown.mjs` містить набір чистих утиліт для генерації згенерованих маркдаун-файлів (зокрема `AGENTS.md` та `CLAUDE.md`) у межах CLI `n-cursor`. Він виконує дві основні задачі:
 
 1. Розгортає Mustache-подібні блоки `{{#section}}…{{/section}}` із простою підстановкою одного поля `{{prop}}` для кожного елемента переданого масиву.

package/scripts/lib/docs/gha-workflow.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: gha-workflow.mjs
+resource: npm/scripts/lib/gha-workflow.mjs
 docgen:
-  source: npm/scripts/lib/gha-workflow.mjs
   crc: 266986bf
 ---
 
-# gha-workflow.mjs
-
-## Огляд
-
 Модуль `gha-workflow.mjs` — це набір допоміжних чистих функцій для **структурного аналізу GitHub Actions workflow-файлів** (`.yml`) після їх розбору як YAML.
 
 Призначення модуля — замінити крихкий пошук підрядків у сирому тексті workflow-файла на **типобезпечну** перевірку значень `uses:` та `run:` у кроках (`steps`) робіт (`jobs`). Модуль використовується сценаріями перевірки (checkers) проєктних правил:

package/scripts/lib/docs/index.md

@@ -0,0 +1,44 @@
+---
+type: Directory Index
+title: npm/scripts/lib
+resource: npm/scripts/lib/
+---
+
+# npm/scripts/lib
+
+| Файл | Тип |
+|---|---|
+| [assert-project-root.mjs](assert-project-root.md) | JS Module |
+| [changed-files.mjs](changed-files.md) | JS Module |
+| [check-mdc-template-refs.mjs](check-mdc-template-refs.md) | JS Module |
+| [check-reporter.mjs](check-reporter.md) | JS Module |
+| [diff-added-lines.mjs](diff-added-lines.md) | JS Module |
+| [discover-check-rules-from-cursor.mjs](discover-check-rules-from-cursor.md) | JS Module |
+| [discover-checkable-rules.mjs](discover-checkable-rules.md) | JS Module |
+| [ensure-tool.mjs](ensure-tool.md) | JS Module |
+| [generated-markdown.mjs](generated-markdown.md) | JS Module |
+| [gha-workflow.mjs](gha-workflow.md) | JS Module |
+| [inline-template-links.mjs](inline-template-links.md) | JS Module |
+| [list-project-rules-mdc.mjs](list-project-rules-mdc.md) | JS Module |
+| [list-rule-ids.mjs](list-rule-ids.md) | JS Module |
+| [load-cursor-config.mjs](load-cursor-config.md) | JS Module |
+| [mirror-parity.mjs](mirror-parity.md) | JS Module |
+| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md) | JS Module |
+| [resolve-target-files.mjs](resolve-target-files.md) | JS Module |
+| [root-notice.mjs](root-notice.md) | JS Module |
+| [rule-meta-helpers.mjs](rule-meta-helpers.md) | JS Module |
+| [rule-meta.mjs](rule-meta.md) | JS Module |
+| [rule-predicates.mjs](rule-predicates.md) | JS Module |
+| [run-conftest-batch.mjs](run-conftest-batch.md) | JS Module |
+| [run-lint-step.mjs](run-lint-step.md) | JS Module |
+| [run-rule-cli.mjs](run-rule-cli.md) | JS Module |
+| [run-rule.mjs](run-rule.md) | JS Module |
+| [run-standard-lint.mjs](run-standard-lint.md) | JS Module |
+| [run-standard-rule.mjs](run-standard-rule.md) | JS Module |
+| [skill-meta.mjs](skill-meta.md) | JS Module |
+| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md) | JS Module |
+| [template.mjs](template.md) | JS Module |
+| [timing-summary.mjs](timing-summary.md) | JS Module |
+| [workspaces.mjs](workspaces.md) | JS Module |
+| [worktree-notice.mjs](worktree-notice.md) | JS Module |
+| [worktree.mjs](worktree.md) | JS Module |

package/scripts/lib/docs/inline-template-links.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: inline-template-links.mjs
+resource: npm/scripts/lib/inline-template-links.mjs
 docgen:
-  source: npm/scripts/lib/inline-template-links.mjs
   crc: 7726f0ef
 ---
 
-# inline-template-links.mjs
-
-## Огляд
-
 Модуль `inline-template-links.mjs` — допоміжна утиліта для **build-кроку обробки `.mdc`-правил**. Її роль: у текстовому вмісті `.mdc`-документа знайти Markdown-посилання, які ведуть на template-файли (шлях містить сегмент `/template/` або `/templates/`), і **замінити** ці посилання на **інлайн fenced-блоки** з фактичним вмістом target-файлу.
 
 Простими словами: замість того щоб у згенерованому правилі читач бачив посилання `[конфіг](./templates/package.json.snippet.json)`, він побачить безпосередньо назву реального файлу (`package.json`) і fenced-блок із його вмістом — це робить правило «самодостатнім», без потреби клікати по лінках.

package/scripts/lib/docs/list-project-rules-mdc.md

@@ -1,15 +1,13 @@
 ---
+type: JS Module
+title: list-project-rules-mdc.mjs
+resource: npm/scripts/lib/list-project-rules-mdc.mjs
 docgen:
-  source: npm/scripts/lib/list-project-rules-mdc.mjs
   crc: e17e0855
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-# list-project-rules-mdc.mjs
-
-## Огляд
-
 Експортує константу CURSOR_RULES_DIR, яка вказує на каталог правил у проєкті-споживачі. Надає функцію для отримання відсортованого списку всіх файлів правил `.mdc` з цього каталогу.
 
 ## Поведінка

package/scripts/lib/docs/list-rule-ids.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: list-rule-ids.mjs
+resource: npm/scripts/lib/list-rule-ids.mjs
 docgen:
-  source: npm/scripts/lib/list-rule-ids.mjs
   crc: 5ef1ead5
 ---
 
-# list-rule-ids.mjs
-
-## Огляд
-
 Модуль `list-rule-ids.mjs` — невелика бібліотечна утиліта, призначена для перебору директорій-правил у каталозі `npm/rules/` та повернення відсортованого алфавітно списку ідентифікаторів правил, які реально містять виконуваний модуль `fix.mjs`.
 
 Логіка модуля побудована навколо архітектурної інваріанти проєкту: після так званої «атомарної міграції» кожне валідне правило **зобов'язане** мати файл `fix.mjs` у власній директорії `rules/<id>/`. Будь-яка піддиректорія без `fix.mjs` вважається або «не-правилом» (службова тека), або заглушкою-чернеткою — і ігнорується. Прихованих директорій (імена, що починаються з `.`) також не існує в результаті.

package/scripts/lib/docs/load-cursor-config.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: load-cursor-config.mjs
+resource: npm/scripts/lib/load-cursor-config.mjs
 docgen:
-  source: npm/scripts/lib/load-cursor-config.mjs
   crc: c86a80f4
 ---
 
-# load-cursor-config.mjs
-
-## Огляд
-
 Утилітарний модуль для читання конфігураційного файлу `.n-cursor.json` з кореня репозиторію. Призначений для використання check-скриптами, що обходять файлову систему й мають виключати певні каталоги зі сканування.
 
 Наразі експортує лише одну публічну функцію — `loadCursorIgnorePaths(root)`, яка повертає нормалізовані абсолютні posix-шляхи з масиву `ignore` у конфізі. Якщо конфіг відсутній, пошкоджений, або поле `ignore` має невалідний формат — функція повертає порожній масив без кидання винятків (fail-soft підхід).

package/scripts/lib/docs/mirror-parity.md

@@ -1,11 +1,11 @@
 ---
+type: JS Module
+title: mirror-parity.mjs
+resource: npm/scripts/lib/mirror-parity.mjs
 docgen:
-  source: npm/scripts/lib/mirror-parity.mjs
   crc: 15dc336a
 ---
 
-## Огляд
-
 Модуль `mirror-parity.mjs` забезпечує перевірку парності (parity) між «дзеркальними» файлами правил Cursor у `.cursor/rules/n-<id>.mdc` та їх канонічними джерелами у `npm/rules/<id>/<id>.mdc`. Ідея така: репозиторій містить два представлення одного й того ж правила:
 
 - канонічне джерело правила лежить у `npm/rules/<id>/<id>.mdc` (з можливими посиланнями на шаблони у тій самій теці);