@nitra/cursor 5.0.3 → 5.2.0

package/skills/doc-aggregate/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: doc-aggregate
+description: >-
+  Агрегуюча документація за запитом: module-summary на кожен логічний модуль (docs/ARCHITECTURE.md) і доменні доки бізнес-процесів у кореневій docs/ — синтез поверх готових файлових док (doc-files), батч-диспатч субагентів у worktree
+---
+
+# doc-aggregate — агрегуюча документація (за запитом)
+
+## Мета
+
+Синтезувати документацію вищого рівня поверх **готових файлових док** (їх підтримує
+обовʼязковий скіл `doc-files`). Два рівні, строго послідовно:
+
+1. **Tier 2 — module-summary**: `<module_root>/docs/ARCHITECTURE.md`, субагент на модуль.
+2. **Tier 3 — доменні доки**: `docs/<домен>.md` у кореневій `docs/`, субагент-синтезатор
+   виділяє бізнес-домени й пише файл на кожен домен.
+
+Агрегат ніколи не випереджає джерело: Tier 3 — лише після завершення всього Tier 2.
+Цей скіл викликається **за запитом** (не обовʼязковий крок задачі).
+
+## ⚠️ Паралелізм
+
+Tier 2 — батчами **по 5** субагентів одночасно (кожен пише свій файл, гонок немає).
+Tier 3 — **один** субагент-синтезатор після завершення всього Tier 2.
+
+## Передумова
+
+- Доступний `npx @nitra/cursor`.
+- Файлові доки мають бути свіжі. Перевір і за потреби онови перед агрегацією:
+
+```bash
+npx @nitra/cursor doc-files check --git
+```
+
+Якщо багато застарілих — спершу прожени `npx @nitra/cursor doc-files gen`.
+
+## Крок 1: Tier 2 — module-summary
+
+Зібрати список модулів:
+
+```bash
+npx @nitra/cursor doc-aggregate modules
+```
+
+Команда друкує JSON-масив (усі шляхи абсолютні):
+
+```json
+[
+  {
+    "moduleRoot": "/abs/npm/rules/adr",
+    "relRoot": "npm/rules/adr",
+    "slug": "npm-rules-adr",
+    "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
+    "members": ["npm/rules/adr/index.mjs"],
+    "exists": false
+  }
+]
+```
+
+module-summary **завжди регенерується** (це агрегат — поле `exists` ігноруй). Розбий модулі
+на батчі по 5 і диспатч субагентів. Промпт кожного (підстав `relRoot`, `docPath`, `members`):
+
+```
+Напиши module-summary для одного логічного модуля.
+
+МОДУЛЬ: <relRoot>
+ЗАПИСАТИ В: <docPath>
+ФАЙЛИ МОДУЛЯ (members): <members>
+
+Кроки:
+1. Прочитай файлові доки членів модуля. <member> — sourcePath відносно кореня проєкту
+   (= поточний CWD); його файлова дока — <CWD>/<dir>/docs/<stem>.md. За потреби зазирни
+   в самі файли.
+2. Створи теку для <docPath>, якщо її немає.
+3. Запиши markdown у <docPath> за тими ж правилами стилю, що й файлова дока
+   (українська, чистий Markdown, контекстна незалежність, без HTML).
+
+Секції module-summary:
+## Огляд модуля — призначення модуля <relRoot>, його роль у проєкті.
+## Ключові файли — список із кліковими посиланнями (відносними до розташування цього
+   ARCHITECTURE.md) на члени модуля та їхні файлові доки.
+## Публічний API — що модуль експортує назовні.
+## Внутрішній потік — як компоненти модуля взаємодіють.
+## Підмодулі — вкладені модулі, якщо є.
+
+Поверни лише підтвердження, що файл <docPath> записано.
+```
+
+## Крок 2: Tier 3 — доменні доки
+
+Після завершення **всіх** module-summary диспатч **одного** субагента-синтезатора.
+У промпт підстав конкретний перелік шляхів module-summary (`<module_root>/docs/ARCHITECTURE.md`
+кожного модуля з виводу `doc-aggregate modules`), а не інструкцію їх шукати. Промпт:
+
+```
+Синтезуй доменну документацію бізнес-процесів проєкту.
+
+ДЖЕРЕЛА (module-summary, читай усі): <перелік шляхів ARCHITECTURE.md, підставлений вище>
+
+Кроки:
+1. Прочитай усі module-summary.
+2. Виділи бізнес-домени та процеси (можуть перетинати межі модулів). Доменів може бути багато.
+3. Для КОЖНОГО домену запиши окремий файл docs/<домен>.md у кореневій docs/:
+   - назва файлу — короткий kebab-slug домену;
+   - не перезаписуй файлові доки кореневих файлів у docs/ (напр. app.md, eslint.config.md):
+     якщо слаґ домену збігається з іменем такого файлу — додай суфікс -domain
+     (напр. app-domain.md). Інакше пиши docs/<домен>.md як є;
+   - опиши бізнес-процес домену з кліковими відносними посиланнями на module-summary, конкретні файли й директорії.
+
+Правила стилю — ті ж (українська, чистий Markdown, контекстна незалежність, без HTML).
+
+Поверни перелік створених файлів docs/<домен>.md.
+```
+
+## Крок 3: Підсумок
+
+```
+✓ doc-aggregate завершено.
+Tier 2 (модулі): <M> module-summary.
+Tier 3 (домени): <D> доменних доків у docs/.
+```
+
+Перелічи файли з помилками (субагент впав або не записав `docPath`), якщо такі є.
+Помилка одного модуля не зупиняє решту.
+
+## Нотатки
+
+- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
+- Файлові доки (Tier 1) — окремий обовʼязковий скіл `doc-files`; цей скіл їх не пише, лише агрегує.

package/skills/doc-aggregate/js/docgen-ignore.mjs

@@ -0,0 +1,9 @@
+/**
+ * Re-export спільного списку ignore-глобів зі скіла doc-files.
+ *
+ * Канонічне джерело — `npm/skills/doc-files/js/docgen-ignore.mjs`: обидва скіли
+ * (file-level доки і агрегати) мусять бачити однакове дерево кодових файлів,
+ * інакше агрегат посилатиметься на файли без док (або навпаки). Залежність
+ * спрямована doc-aggregate → doc-files за ADR про розбиття docgen.
+ */
+export * from '../../doc-files/js/docgen-ignore.mjs'

package/skills/{docgen → doc-aggregate}/js/docgen-scan.mjs

@@ -13,9 +13,7 @@ const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
 const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
 
 /**
- * Чи корінь має system-wide docs layout.
- * Такий корінь зарезервований під репозиторні docs/adr, docs/explanation тощо,
- * тому file-level docs у нього не пишемо.
+ * Чи корінь має system-wide docs layout (зарезервований під repo docs/adr тощо).
  * @param {string} root абсолютний корінь обходу
  * @returns {boolean} true — корінь system-wide docs
  */
@@ -26,7 +24,7 @@ function isSystemWideDocsRoot(root) {
 /**
  * Чи є файл кодовим джерелом для документування.
  * @param {string} fileName базове ім'я файлу
- * @returns {boolean} true — документуємо; false — пропускаємо
+ * @returns {boolean} true — документуємо
  */
 export function isSourceFile(fileName) {
   if (fileName.endsWith('.d.ts')) return false
@@ -35,30 +33,14 @@ export function isSourceFile(fileName) {
 }
 
 /**
- * Обчислює шлях md-документа для кодового файлу: тека `docs/` поряд із джерелом.
- * Якщо `sourcePath` відносний, `docPath` теж відносний; якщо абсолютний — абсолютний.
- * @param {string} sourcePath шлях до джерела (відносний або абсолютний)
- * @returns {string} шлях до `<dir>/docs/<stem>.md` у тому ж просторі шляхів
- */
-export function docPathForSource(sourcePath) {
-  const dir = path.dirname(sourcePath)
-  const stem = path.basename(sourcePath, path.extname(sourcePath))
-  return path.join(dir, 'docs', `${stem}.md`)
-}
-
-/**
- * Рекурсивно обходить дерево від `root`, повертає кодові файли для документування.
- * Синхронний `readdirSync` — детермінований порядок і простий рекурсивний обхід без
- * гонок; обсяг дерева проєкту це дозволяє.
+ * Рекурсивно збирає кодові файли проєкту (posix-шляхи від кореня).
  * @param {string} root абсолютний корінь обходу
- * @returns {Array<{sourcePath:string, docPath:string, exists:boolean}>} список кандидатів з відносними шляхами
+ * @returns {string[]} sourcePath-и
  */
-export function scanForDocgen(root) {
+export function scanSourceFiles(root) {
   const results = []
 
-  /**
-   * @param {string} dir поточний каталог обходу
-   */
+  /** @param {string} dir поточний каталог обходу */
   function walk(dir) {
     let entries
     try {
@@ -76,12 +58,7 @@ export function scanForDocgen(root) {
         if (isSystemWideDocsRoot(root) && path.dirname(relPath) === '.') continue
         const sourcePath = relPath.split(path.sep).join('/')
         if (isDocgenIgnored(sourcePath)) continue
-        const docPath = docPathForSource(sourcePath)
-        results.push({
-          sourcePath,
-          docPath,
-          exists: existsSync(path.join(root, docPath))
-        })
+        results.push(sourcePath)
       }
     }
   }
@@ -98,7 +75,6 @@ export function scanForDocgen(root) {
  */
 export function slugForModule(root, moduleRoot) {
   const rel = path.relative(root, moduleRoot)
-  // корінь репо: фіксований sentinel 'root'
   if (rel === '') return 'root'
   return rel
     .split(path.sep)
@@ -108,7 +84,6 @@ export function slugForModule(root, moduleRoot) {
 
 /**
  * Знаходить корені модулів — теки з `package.json` (корінь завжди модуль).
- * Ті ж ignore-glob правила, тож `package.json` у службових деревах не враховується.
  * @param {string} root абсолютний корінь обходу
  * @returns {string[]} абсолютні шляхи коренів модулів
  */
@@ -159,17 +134,17 @@ export function nearestModuleRoot(filePath, moduleRoots) {
  * Лістить логічні модулі проєкту з членами-файлами і docPath module-summary.
  * Модулі без кодових файлів пропускаються.
  * @param {string} root абсолютний корінь обходу
- * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — sourcePath-и, відносні від root)
+ * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — sourcePath-и від root)
  */
 export function scanForModules(root) {
-  const files = scanForDocgen(root)
+  const files = scanSourceFiles(root)
   const moduleRoots = findModuleRoots(root)
   const byRoot = new Map()
-  for (const file of files) {
-    const moduleRoot = nearestModuleRoot(path.join(root, file.sourcePath), moduleRoots)
+  for (const sourcePath of files) {
+    const moduleRoot = nearestModuleRoot(path.join(root, sourcePath), moduleRoots)
     if (moduleRoot === null) continue
     if (!byRoot.has(moduleRoot)) byRoot.set(moduleRoot, [])
-    byRoot.get(moduleRoot).push(file.sourcePath)
+    byRoot.get(moduleRoot).push(sourcePath)
   }
 
   const results = []
@@ -190,7 +165,7 @@ export function scanForModules(root) {
 }
 
 /**
- * Парсить `--root <dir>` з argv; default — cwd.
+ * Парсить `--root <dir>`; default — cwd.
  * @param {string[]} argv аргументи після підкоманди
  * @returns {string} абсолютний корінь
  */
@@ -200,42 +175,22 @@ export function resolveRoot(argv) {
 }
 
 /**
- * Парсить `--root <dir>` (default — cwd), сканує і друкує JSON-масив у stdout.
- * @param {string[]} argv аргументи після назви субкоманди (наприклад ['--root', '<dir>'])
- * @returns {Promise<number>} exit-код: 0 — успіх, 1 — корінь не існує
- */
-export async function runDocgenScanCli(argv) {
-  const root = resolveRoot(argv)
-
-  if (!existsSync(root) || !statSync(root).isDirectory()) {
-    console.error(`docgen scan: корінь не існує або не є директорією: ${root}`)
-    return 1
-  }
-
-  const items = await scanForDocgen(root)
-  console.log(JSON.stringify(items, null, 2))
-  return 0
-}
-
-/**
- * Парсить `--root`, сканує модулі і друкує JSON-масив у stdout.
- * @param {string[]} argv аргументи після назви субкоманди (наприклад ['--root', '<dir>'])
- * @returns {Promise<number>} exit-код: 0 — успіх, 1 — корінь не існує
+ * `doc-aggregate modules` — сканує модулі і друкує JSON-масив у stdout.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {number} exit-код: 0 — успіх, 1 — корінь не існує
  */
-export async function runDocgenModulesCli(argv) {
+export function runDocAggregateModulesCli(argv) {
   const root = resolveRoot(argv)
-
   if (!existsSync(root) || !statSync(root).isDirectory()) {
-    console.error(`docgen modules: корінь не існує або не є директорією: ${root}`)
+    console.error(`doc-aggregate modules: корінь не існує або не є директорією: ${root}`)
     return 1
   }
-
-  const items = await scanForModules(root)
-  console.log(JSON.stringify(items, null, 2))
+  console.log(JSON.stringify(scanForModules(root), null, 2))
   return 0
 }
 
 if (isRunAsCli(import.meta.url)) {
-  // Прямий запуск: `node skills/docgen/js/docgen-scan.mjs --root <dir>`
-  process.exitCode = await runDocgenScanCli(process.argv.slice(2))
+  // Прямий запуск: `node skills/doc-aggregate/js/docgen-scan.mjs modules --root <dir>`
+  const [sub, ...rest] = process.argv.slice(2)
+  process.exitCode = runDocAggregateModulesCli(sub === 'modules' ? rest : process.argv.slice(2))
 }

package/skills/doc-aggregate/js/docs/docgen-ignore.md

@@ -0,0 +1,21 @@
+---
+docgen:
+  source: npm/skills/doc-aggregate/js/docgen-ignore.mjs
+  crc: 8821af65
+---
+
+# docgen-ignore
+
+## Огляд
+
+Re-export спільного списку ignore-глобів зі скіла doc-files: обидва скіли документації (пофайлові доки й агрегати) мусять бачити однакове дерево кодових файлів, інакше агрегат посилатиметься на файли без док або навпаки.
+
+## Поведінка
+
+1. Модуль не має власної логіки: повністю делегує канонічному джерелу в doc-files і повторно експортує його API (список глобів і перевірку належності шляху до ігнорованих).
+2. Напрям залежності — doc-aggregate → doc-files, відповідно до рішення про розбиття docgen на два скіли.
+
+## Гарантії поведінки
+
+- Списки ignore-глобів двох скілів не можуть розійтися — джерело одне.
+- Read-only, без мережі й побічних ефектів.

package/skills/doc-files/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: doc-files
+description: >-
+  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue/py) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
+---
+
+# doc-files — файлова документація (обовʼязковий крок)
+
+## Мета
+
+Для кожного кодового файлу проєкту тримати **актуальну** лаконічну поведінкову `.md`-документацію
+у теці `docs/` **поряд із самим файлом** (`<dir>/docs/<stem>.md`). Це **обовʼязковий крок кожної
+задачі** — як `lint`: після зміни коду його дока має бути перегенерована.
+
+Застарілість визначається **детерміновано за CRC**: кожна дока несе у frontmatter контрольну
+суму байтів джерела на момент генерації. Дока **застаріла**, якщо її немає або
+`crc(поточне джерело) ≠ crc у frontmatter`.
+
+```markdown
+---
+docgen:
+  source: src/lib/foo.js
+  crc: a3f1c9e0
+---
+
+## Огляд
+
+…
+```
+
+## Оркестрацію веде JS, не модель; конвеєр — local-only
+
+Уся важка робота — черга, батчинг, виклики LLM і штамп CRC — живе в JS-команді
+`doc-files gen`. **Ти не диспатчиш субагентів і не тримаєш сотні файлів у контексті**
+— тому навіть масовий перший прогін усього репо не «заморює». Цей скіл **тонкий**: твоє завдання —
+запустити генерацію і прочитати підсумок.
+
+Конвеєр **суто локальний** (ADR `260610-2228`): будь-який файл генерується локальною
+моделлю (`omlx/…` напряму), хмарних ескалацій немає. Якщо det-оцінка нижча за поріг —
+дока все одно пишеться з **degraded-маркером** (`score`/`issues` у frontmatter, CRC свіжий),
+а перегенерація таких док — окремою командою пізніше.
+
+## Передумова
+
+- Поточна директорія — корінь проєкту (`requireRoot`), не worktree.
+- Доступний `npx @nitra/cursor`.
+
+## Workflow
+
+### Крок 1: Генерація застарілих/відсутніх док
+
+```bash
+npx @nitra/cursor doc-files gen
+```
+
+Команда сама: перевіряє omlx (preflight: «сервер лежить» / «модель не влазить у пам'ять
+зайнятої машини» / «потрібен API-ключ» → одна зрозуміла зупинка замість лавини «✗») →
+сканує проєкт → фільтрує застарілі (`stale`) → генерує локальною моделлю → пише доку зі
+**свіжим CRC** (і degraded-маркером, якщо не дотягнула) → друкує прогрес і підсумок.
+
+- Для дуже великого прогону можна порціями: `--from N --limit M`.
+- Перегенерувати **всі** доки (не лише застарілі): `--overwrite`.
+- Перегенерувати лише degraded (свіжі за CRC, score < порогу): `--retry-degraded`.
+
+### Крок 2: Підтвердження
+
+Дочекайся підсумку `✓ OK: <N>  ⚠ degraded: <D>  ✗ Err: <E>`. Якщо є помилки — перелічи
+проблемні файли. Exit-код `1` означає, що хоча б один файл не згенерувався (або не пройшов
+preflight). Degraded — не помилка: дока існує, борг видно у `check --degraded`.
+
+### Крок 3 (за потреби): перевірка перед завершенням
+
+```bash
+npx @nitra/cursor doc-files check --git
+```
+
+Перевіряє змінені у задачі джерела (`git diff --name-only HEAD`) проти CRC їхніх док.
+Цю ж перевірку виконує **Stop-hook** як твердий гейт: завершити задачу зі застарілими
+доками не можна (виняток — масовий прогін понад поріг `N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50).
+Degraded-доки гейт **не** блокує (CRC свіжий); їх список — `doc-files check --degraded`.
+
+## Правила стилю документа (за adr/ci4)
+
+- Мова — **УКРАЇНСЬКА** для всього тексту. Code identifiers, шляхи, імена API, команди — як у коді.
+- **Чистий Markdown.** Жодних HTML-обгорток. Єдиний виняток — машинний `docgen:`-frontmatter із CRC.
+- **Фокус на ПОВЕДІНЦІ, не реалізації.** ЩО і НАВІЩО, а не як саме зроблено.
+- Не перелічуй модулі стандартної бібліотеки і внутрішні назви допоміжних функцій.
+- Кожна секція самодостатня (без «як вище», «ця функція»).
+- Секції (лише доречні): `## Огляд`, `## Поведінка`, `## Публічний API`, `## Де використовується`,
+  `## Гарантії поведінки`; для `.vue` — `## Інтерфейс компонента`.
+- Не вигадуй деталей, яких немає в коді.
+
+## Нотатки
+
+- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
+- Scanner ігнорує `node_modules`, `dist`, `.git`, `__pycache__`, `coverage`, `.cursor`, `.claude`,
+  усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`. Кореневий repo `docs/` —
+  system-wide only: file-level docs туди не пишуться. Список glob-ів — `docgen-ignore.mjs`.
+- Агрегуюча документація (module-summary, доменні доки) — окремий скіл `doc-aggregate`, за запитом.
+- Для наявних док без CRC одноразово: `npx @nitra/cursor doc-files stamp` (штампує frontmatter без LLM).

package/skills/doc-files/js/docgen-crc.mjs

@@ -0,0 +1,164 @@
+/**
+ * CRC32 джерела + YAML-frontmatter файлової документації.
+ *
+ * Кожна файлова дока несе у frontmatter контрольну суму байтів джерела на момент
+ * генерації. Це детермінований маркер застарілості: `crc32(поточне джерело)` звіряється
+ * з `crc` у доці — розбіжність (або відсутня дока) означає, що дока відстала від коду.
+ * CRC не залежить від git-стану (rebase, незакомічене, гілки), тож придатний і для
+ * per-edit hook (бачить лише змінений файл), і для повного сканування.
+ *
+ * Degraded-маркер (ADR 260610-2228): якщо локальний конвеєр не дотягнув до порогу
+ * якості, дока все одно пишеться, а frontmatter додатково несе `score` (det-оцінка)
+ * та `issues` (коди проблем). CRC при цьому свіжий — Stop-гейт не блокує задачі через
+ * слабкість моделі; борг видимий через `check --degraded` і адресно перегенеровується
+ * через `gen --retry-degraded`.
+ *
+ * Frontmatter — єдиний дозволений виняток із правила «чистий Markdown без HTML»:
+ * це машинні метадані, не контент. Формат:
+ *
+ *   ---
+ *   docgen:
+ *     source: src/lib/foo.js
+ *     crc: a3f1c9e0
+ *     score: 55
+ *     issues: short-behavior,internal-name:bar
+ *   ---
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { crc32 as zlibCrc32 } from 'node:zlib'
+import { env } from 'node:process'
+
+/** Поріг degraded: дока зі `score` нижче вважається неякісною. */
+export const QUALITY_THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? 70) || 70
+
+/**
+ * CRC32 вмісту у hex (8 символів, з провідними нулями). Делегує у нативний
+ * `node:zlib.crc32` — без ручної бітової арифметики.
+ * @param {string|Buffer} input текст або байти джерела
+ * @returns {string} CRC32 у hex
+ */
+export function crc32(input) {
+  const buf = typeof input === 'string' ? Buffer.from(input, 'utf8') : input
+  return zlibCrc32(buf).toString(16).padStart(8, '0')
+}
+
+/** Провідний YAML-frontmatter-блок `---\n…\n---`. */
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/u
+const SOURCE_RE = /^[ \t]{0,8}source:[ \t]{0,8}(.+)$/mu
+const CRC_RE = /^[ \t]{0,8}crc:[ \t]{0,8}(.+)$/mu
+const SCORE_RE = /^[ \t]{0,8}score:[ \t]{0,8}(\d+)$/mu
+const ISSUES_RE = /^[ \t]{0,8}issues:[ \t]{0,8}(.+)$/mu
+const LEADING_NEWLINES_RE = /^\n+/u
+const ISSUE_CODE_TAIL_RE = /[,:]$/u
+
+/**
+ * Парсить frontmatter файлової доки. Без блоку — `data:null` і `body` дорівнює входу.
+ * Поля `score`/`issues` опційні (back-compat зі старими доками): без них —
+ * `score:null`, `issues:[]`.
+ * @param {string} md вміст md-файлу
+ * @returns {{ data: { source: string|null, crc: string|null, score: number|null, issues: string[] }|null, body: string }} метадані + тіло без frontmatter
+ */
+export function parseDocFrontmatter(md) {
+  const match = md.match(FRONTMATTER_RE)
+  if (!match) return { data: null, body: md }
+  const block = match[1]
+  const scoreRaw = block.match(SCORE_RE)?.[1]
+  const issuesRaw = block.match(ISSUES_RE)?.[1]
+  return {
+    data: {
+      source: block.match(SOURCE_RE)?.[1].trim() ?? null,
+      crc: block.match(CRC_RE)?.[1].trim() ?? null,
+      score: scoreRaw === undefined ? null : Number(scoreRaw),
+      issues: issuesRaw
+        ? issuesRaw
+            .split(',')
+            .map(s => s.trim())
+            .filter(Boolean)
+        : []
+    },
+    body: md.slice(match[0].length)
+  }
+}
+
+/** Максимум кодів issues у frontmatter — це маркер, а не повний лог. */
+const MAX_ISSUE_CODES = 8
+
+/**
+ * Нормалізує issues до YAML-безпечних кодів: бере фрагмент до першого пробілу
+ * (зрізає людиночитні хвости помилок), відкидає порожні, обмежує кількість.
+ * @param {string[]} issues сирі issue-рядки від скорера
+ * @returns {string[]} коди без пробілів
+ */
+function issueCodes(issues) {
+  return issues
+    .map(i => String(i).split(' ')[0].replace(ISSUE_CODE_TAIL_RE, ''))
+    .filter(Boolean)
+    .slice(0, MAX_ISSUE_CODES)
+}
+
+/**
+ * Будує frontmatter-блок із шляхом джерела, CRC і (опційно) якістю.
+ * @param {string} source відносний шлях джерела
+ * @param {string} crc CRC32 джерела у hex
+ * @param {{ score: number, issues?: string[] }|null} [quality] det-оцінка доки; null — без полів якості
+ * @returns {string} рядок `---\ndocgen:\n  source: …\n  crc: …[\n  score: …][\n  issues: …]\n---\n`
+ */
+export function buildDocFrontmatter(source, crc, quality = null) {
+  const lines = [`source: ${source}`, `crc: ${crc}`]
+  if (quality && typeof quality.score === 'number') {
+    lines.push(`score: ${quality.score}`)
+    const codes = issueCodes(quality.issues ?? [])
+    if (codes.length > 0) lines.push(`issues: ${codes.join(',')}`)
+  }
+  const indented = lines.map(l => '  ' + l).join('\n')
+  return `---\ndocgen:\n${indented}\n---\n`
+}
+
+/**
+ * (Пере)штампує frontmatter у md-доку: знімає наявний блок і додає свіжий.
+ * @param {string} md тіло доки (з frontmatter або без)
+ * @param {string} source відносний шлях джерела
+ * @param {string} crc CRC32 джерела у hex
+ * @param {{ score: number, issues?: string[] }|null} [quality] det-оцінка доки
+ * @returns {string} md зі свіжим frontmatter
+ */
+export function stampDoc(md, source, crc, quality = null) {
+  const { body } = parseDocFrontmatter(md)
+  return `${buildDocFrontmatter(source, crc, quality)}\n${body.replace(LEADING_NEWLINES_RE, '')}`
+}
+
+/**
+ * CRC, збережений у frontmatter доки; `null` — доки немає або CRC відсутній.
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {string|null} CRC32 з frontmatter або null
+ */
+export function readDocCrc(docAbsPath) {
+  if (!existsSync(docAbsPath)) return null
+  return parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data?.crc ?? null
+}
+
+/**
+ * Якість, збережена у frontmatter доки.
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {{ score: number|null, issues: string[] }} `score:null` — доки немає або поле відсутнє
+ */
+export function readDocQuality(docAbsPath) {
+  if (!existsSync(docAbsPath)) return { score: null, issues: [] }
+  const data = parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data
+  return { score: data?.score ?? null, issues: data?.issues ?? [] }
+}
+
+/**
+ * Стан застарілості доки відносно її джерела.
+ * `missing` — доки немає; `crc-mismatch` — CRC джерела ≠ CRC у доці; інакше свіжа.
+ * @param {string} sourceAbsPath абсолютний шлях джерела
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {{ stale: boolean, reason: 'missing'|'crc-mismatch'|null }} стан застарілості
+ */
+export function staleness(sourceAbsPath, docAbsPath) {
+  const docCrc = readDocCrc(docAbsPath)
+  if (docCrc === null) return { stale: true, reason: 'missing' }
+  const srcCrc = crc32(readFileSync(sourceAbsPath))
+  if (srcCrc !== docCrc) return { stale: true, reason: 'crc-mismatch' }
+  return { stale: false, reason: null }
+}