@nitra/cursor 5.3.4 → 5.4.0

package/scripts/coverage-classify/docs/index.md

@@ -1,218 +1,32 @@
-# `coverage-classify/index.mjs`
+---
+docgen:
+  source: npm/scripts/coverage-classify/index.mjs
+  crc: 06249ac8
+  score: 100
+---
 
-## Огляд
-
-Модуль `coverage-classify/index.mjs` — це **публічна точка входу** (Public API) класифікатора survived-мутантів за допомогою Claude API від Anthropic. Він відповідає за оркестрацію LLM-класифікації мутантів, які пережили mutation-testing раунд (тобто не були вбиті жодним тестом), і повертає для кожного з них вердикт у форматі `{ verdict, confidence, reason, suggestedTest? }`.
-
-Призначення модуля — допомогти автоматичним інструментам типу `/n-coverage-fix` ухвалювати рішення, чи варто дописувати тест на конкретний survived-мутант, чи можна його ігнорувати як equivalent / not-worth-testing.
-
-Ключові архітектурні характеристики:
-
-- **Graceful degradation:** відсутність змінної `ANTHROPIC_API_KEY` або непрацездатний dynamic import пакета `@anthropic-ai/sdk` не приводить до краху — функція мовчки повертає порожній масив `[]`, попередньо вивівши попередження у `console.warn`.
-- **Persistent cache:** результати класифікації кешуються на диск через утиліти з `./cache.mjs`. При зміні `MODEL` кеш повністю інвалідується (entries чистяться, поле `model` оновлюється). Це гарантує консистентність вердиктів між запусками за умови незмінного контексту мутанта.
-- **Prompt caching на стороні API:** системний промпт передається з `cache_control: { type: 'ephemeral' }` — усі мутанти одного прогону reuse кешований префікс на стороні Anthropic API (економія токенів).
-- **Retry з експоненційним backoff:** кожен мутант отримує до `MAX_RETRIES + 1 = 3` спроб; між спробами — затримка `retryDelayMs * 2 ** attempt`. Після вичерпання спроб — повертається **conservative fallback** `worth-testing/confidence=0`, щоб не втратити мутант з виду.
-
-Модуль не виконує мережевих викликів самостійно — він делегує їх в `client.messages.create(...)` (за замовчуванням це інстанс `new Anthropic()` з SDK).
-
-## Експорти / API
-
-| Експорт    | Тип      | Опис                                                                                             |
-| ---------- | -------- | ------------------------------------------------------------------------------------------------ |
-| `classify` | function | Іменований async-експорт. Класифікує всіх survived-мутантів і повертає масив `{ key, verdict }`. |
-
-Інші ідентифікатори файлу (`MODEL`, `MAX_RETRIES`, `DEFAULT_RETRY_DELAY_MS`, `FALLBACK_VERDICT`, `classifyOne`) — **внутрішні**, не експортуються.
-
-### Сигнатура `classify`
-
-```js
-export async function classify(survived, cwd, opts = {})
-```
-
-**Параметри:**
-
-- `survived` — `Array<{ file: string, mutants: Array<object>, exampleTest?: object|null, recommendationText?: string|null }>` — список survived-груп. Структура аналогічна до використовуваної в `COVERAGE.md` (звіт mutation-testing). Кожна група відповідає одному файлу та містить масив мутантів.
-- `cwd` — `string` — абсолютний шлях кореня проєкту. Використовується для:
-  - формування дефолтного шляху кешу (`<cwd>/npm/reports/coverage-classify.cache.json`);
-  - резолвінгу шляхів до файлів-джерел мутантів (для побудови юзер-промпта та cache key).
-- `opts` — `{ cachePath?: string, client?: object, retryDelayMs?: number }` — опціональні ін'єкції для тестування:
-  - `cachePath` — кастомний шлях до файлу кешу.
-  - `client` — підставний Anthropic SDK client (для unit-тестів без реальних мережевих викликів). Має мати метод `messages.create(...)`.
-  - `retryDelayMs` — базова затримка для exp-backoff у мс. `0` фактично вимикає sleep між retries (зручно для тестів).
-
-**Повертає:** `Promise<Array<{ key: string, verdict: object }>>`
-
-- `key` — рядок формату `<file>:<line>:<col>:<replacement>`, який однозначно ідентифікує мутант для зовнішнього коду.
-- `verdict` — об'єкт з полями `{ verdict, confidence, reason, suggestedTest? }` (формат описаний у `./verdict-schema.mjs`).
-
-При відсутності API-ключа або SDK — повертає `[]`.
-
-## Функції
-
-### `classify(survived, cwd, opts)` — публічна
-
-**Сигнатура:** `async function classify(survived, cwd, opts = {}) -> Promise<Array<{key, verdict}>>`
-
-**Параметри:** див. розділ «Експорти / API» вище.
-
-**Повертає:** `Promise<Array<{ key: string, verdict: object }>>` — плаский список вердиктів по всіх мутантах усіх груп (порядок: group-by-group, mutant-by-mutant у межах групи).
-
-**Кроки виконання (orchestration):**
-
-1. Резолвить `cachePath` (дефолт: `<cwd>/npm/reports/coverage-classify.cache.json`) та `retryDelayMs` (дефолт: `DEFAULT_RETRY_DELAY_MS = 1000`).
-2. Перевіряє `env.ANTHROPIC_API_KEY`. Якщо відсутній — `console.warn` + `return []`.
-3. Виконує `await import('@anthropic-ai/sdk')`. Якщо пакет не встановлено — `console.warn` + `return []`.
-4. Створює клієнт: `opts.client ?? new Anthropic()`.
-5. Завантажує кеш через `readCache(cachePath)`. Якщо `cache.model !== MODEL` — повністю чистить `cache.entries` і виставляє `cache.model = MODEL` (інвалідація при зміні моделі).
-6. Ітерує `survived.mutants`:
-   - Будує `lookupKey = "<group.file>:<line>:<col>:<replacement>"`.
-   - Обчислює `cacheKey = deriveCacheKey(join(cwd, group.file), mutant)`.
-   - Якщо в кеші є запис — повертає його (нормалізуючи поля, опціонально розгортаючи `suggestedTest`).
-   - Інакше викликає `classifyOne(client, group, mutant, cwd, retryDelayMs)` і записує результат у `cache.entries[cacheKey]` з полем `classifiedAt: new Date().toISOString()` (якщо `cacheKey` truthy).
-7. Зберігає кеш на диск через `writeCache(cachePath, cache)`.
-8. Повертає накопичений `verdicts`.
-
-**Side effects:**
-
-- **Disk I/O:** читання і запис файлу кешу (`<cwd>/npm/reports/coverage-classify.cache.json` за замовчуванням).
-- **Мережа:** виклики `client.messages.create(...)` до Anthropic API (через делегування в `classifyOne`).
-- **stdout/stderr:** `console.warn(...)` при відсутності ключа / SDK / при фатальних retry-фейлах окремих мутантів.
-- **Час:** функція **очікує** мережеві запити послідовно (no parallelism між мутантами) — у гіршому випадку загальна тривалість = `N × (MAX_RETRIES+1) × API_latency + sum(backoff)`.
-- **Стан системи:** мутації `cache` на місці (об'єкт переписується), потім дамп на диск.
-
-### `classifyOne(client, group, mutant, cwd, retryDelayMs)` — внутрішня
-
-**Сигнатура:** `async function classifyOne(client, group, mutant, cwd, retryDelayMs) -> Promise<object>`
+# index.mjs
 
-**Параметри:**
-
-- `client` — `{ messages: { create: Function } }` — Anthropic SDK client (реальний або mock).
-- `group` — `{ file: string }` — група для контексту (з неї потрібно лише `.file` — повний шлях до файлу-джерела).
-- `mutant` — `object` — дані мутанта (передаються в `buildUserPrompt` як `{ ...mutant, file: group.file }`).
-- `cwd` — `string` — корінь проєкту, потрібний для resolving шляхів у `buildUserPrompt`.
-- `retryDelayMs` — `number` — базова затримка для exp-backoff (`0` у тестах вимикає sleep).
-
-**Повертає:** `Promise<object>` — розпарсений вердикт (через `parseVerdict(text)`) або копія `FALLBACK_VERDICT`.
-
-**Кроки виконання:**
-
-1. Будує юзер-промпт: `userPrompt = buildUserPrompt({ ...mutant, file: group.file }, cwd)`.
-2. Цикл `for (attempt = 0; attempt <= MAX_RETRIES; attempt++)`:
-   - Виконує `client.messages.create({ model: MODEL, max_tokens: 1024, system: [{ type:'text', text: SYSTEM_PROMPT, cache_control:{ type:'ephemeral' } }], messages: [{ role:'user', content: userPrompt }] })`.
-   - Дістає текст з `response?.content?.[0]?.text ?? ''`.
-   - Повертає `parseVerdict(text)`. Якщо `parseVerdict` кидає — це впаде як виключення і потрапить в `catch` цієї ж ітерації (тобто буде ще одна retry-спроба).
-3. На `catch`: запам'ятовує `lastError`. Якщо `attempt < MAX_RETRIES && retryDelayMs > 0` — `await setTimeout(retryDelayMs * 2 ** attempt)`.
-4. Після вичерпання спроб: `console.warn` з деталями (file:line:col, кількість спроб, повідомлення останньої помилки) і `return { ...FALLBACK_VERDICT }` (копія, щоб уникнути shared mutation на константі).
-
-**Side effects:**
-
-- Мережевий виклик до Anthropic API (1..MAX_RETRIES+1 разів).
-- `setTimeout` з `node:timers/promises` (async sleep).
-- `console.warn` при фатальному фейлі.
-
-## Залежності
-
-### Внутрішні (relative imports)
-
-| Шлях                   | Що використовується                         | Призначення                                                                                                |
-| ---------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `./cache.mjs`          | `deriveCacheKey`, `readCache`, `writeCache` | Робота з персистентним кешем класифікацій (deriving детермінованого ключа з мутанта + читання/запис JSON). |
-| `./prompt.mjs`         | `buildUserPrompt`, `SYSTEM_PROMPT`          | Побудова промптів для LLM: системний (статичний, кешується) та юзер-промпт (динамічний, per-mutant).       |
-| `./verdict-schema.mjs` | `parseVerdict`                              | Парсинг та валідація JSON-відповіді LLM у структурований об'єкт вердикту.                                  |
-
-### Зовнішні
-
-| Пакет/модуль           | Що використовується          | Як підключено                                                                                           |
-| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `node:path`            | `join`                       | Статичний `import`. Збирання шляхів до cache file та source file.                                       |
-| `node:process`         | `env`                        | Статичний `import`. Читання `ANTHROPIC_API_KEY`.                                                        |
-| `node:timers/promises` | `setTimeout`                 | Статичний `import`. Async sleep для exp-backoff між retries.                                            |
-| `@anthropic-ai/sdk`    | `Anthropic` (default export) | **Dynamic** `await import(...)` всередині `classify` — graceful degradation, якщо пакет не встановлено. |
-
-### Зовнішні артефакти середовища
-
-- **Змінна оточення `ANTHROPIC_API_KEY`** — обов'язкова. Без неї модуль не робить мережевих викликів.
-- **Файл кешу** — за замовчуванням `<cwd>/npm/reports/coverage-classify.cache.json`. Структура: `{ model: string, entries: { [cacheKey]: { verdict, confidence, reason, suggestedTest?, classifiedAt } } }`.
-
-### Константи модуля
-
-| Константа                | Значення                                                     | Призначення                                                                 |
-| ------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
-| `MODEL`                  | `'claude-sonnet-4-6'`                                        | ID моделі Anthropic для класифікації. Зміна → автоматична інвалідація кешу. |
-| `MAX_RETRIES`            | `2`                                                          | Кількість **повторних** спроб (всього спроб: `MAX_RETRIES + 1 = 3`).        |
-| `DEFAULT_RETRY_DELAY_MS` | `1000`                                                       | Базова затримка для exp-backoff (мс). Реальні delays: 1000, 2000, 4000.     |
-| `FALLBACK_VERDICT`       | `{ verdict: 'worth-testing', confidence: 0, reason: '...' }` | Консервативний вердикт при фатальному фейлі (мутант ще не відкидається).    |
-
-## Потік виконання / Використання
-
-### Типовий сценарій виклику
-
-Модуль викликається з вищерівневого pipeline (наприклад, `/n-coverage-fix` або інший CLI поверх mutation-testing звіту):
-
-```js
-import { classify } from '<repo>/npm/scripts/coverage-classify/index.mjs'
-
-// survived зазвичай парситься з COVERAGE.md
-const survived = [
-  {
-    file: 'src/utils/foo.mjs',
-    mutants: [
-      { line: 10, col: 5, replacement: '=== 0', original: '!== 0', mutator: 'EqualityOperator' }
-      // ...
-    ],
-    exampleTest: null,
-    recommendationText: null
-  }
-  // ...
-]
-
-const verdicts = await classify(survived, process.cwd())
-
-for (const { key, verdict } of verdicts) {
-  if (verdict.verdict === 'worth-testing' && verdict.confidence > 0.5) {
-    // дописати тест
-  }
-}
-```
-
-### Стани виходу та граничні випадки
-
-| Стан                                                        | Поведінка                                                                            |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `ANTHROPIC_API_KEY` не виставлений                          | `console.warn` + `return []` (порожній масив, не помилка).                           |
-| Пакет `@anthropic-ai/sdk` не встановлено                    | `console.warn` + `return []`.                                                        |
-| Кеш hit для мутанта                                         | Мережевий виклик не виконується, повертається cached verdict.                        |
-| Кеш miss, успішна класифікація                              | Виклик API, парсинг, запис у кеш, push у verdicts.                                   |
-| Кеш miss, всі retry-спроби впали                            | `console.warn` з деталями + `FALLBACK_VERDICT` push у verdicts (мутант не пропадає). |
-| Зміна `MODEL` у коді                                        | На наступному запуску `cache.entries` повністю обнуляється.                          |
-| `cacheKey === null/undefined` (наприклад, неможливо derive) | Класифікація виконується, але **не** кешується (запис у кеш пропускається).          |
-
-### Послідовність всередині одного прогону (timeline)
+## Огляд
 
-1. Читання `survived` (відповідальність caller'а).
-2. `classify(...)` запускається → preflight перевірки (API key, SDK).
-3. Завантаження дискового кешу → можливе очищення при зміні моделі.
-4. **Послідовно** (не паралельно) для кожного `(group, mutant)`:
-   - Cache lookup (за `cacheKey`).
-   - Якщо miss — `classifyOne` з retry-логікою.
-   - Запис у кеш-об'єкт у пам'яті.
-5. Після обходу всіх мутантів — атомарний `writeCache` на диск.
-6. Повернення `verdicts` caller'у.
+Файл забезпечує класифікацію записів через послідовну спробу отримання результату з кешу, первинного моделі та хмарного сервісу. Якщо кеш не містить даних, відбувається перехід до наступного рівня, доки не буде досягнуто консервативного запасного варіанту. Результати класифікації записуються у кеш. Код спирається на конфіги з файлу coverage-classify.cache.json.
 
-### Особливості та інваріанти
+## Поведінка
 
-- **Послідовність викликів API:** немає паралелізму між мутантами. Це навмисно — обмеження по rate-limits Anthropic API та для стабільної взаємодії з prompt cache.
-- **Prompt cache reuse:** оскільки системний промпт ідентичний для всіх мутантів і помічений `cache_control: ephemeral`, Anthropic API повторно використовує кешований префікс — суттєва економія input-токенів на великих прогонах.
-- **Ідемпотентність:** повторний запуск з тим же `cachePath` і незмінним `survived` дає той же `verdicts` без додаткових мережевих викликів (повний cache hit).
-- **Conservative fallback:** при фейлі класифікації мутант **не** відкидається — він отримує `worth-testing/confidence=0`, що змушує caller свідомо вирішувати, чи приймати такий вердикт. Це усуває ризик «непомітної втрати» мутанта через мережеву помилку.
-- **Defensive copy fallback:** повертається `{ ...FALLBACK_VERDICT }`, а не сам об'єкт — щоб caller'и не могли випадково замутувати константу.
+1. Пошук результату в кеші.
+2. Якщо результат знайдено, використовується збережений вердикт.
+3. Якщо результат не знайдено, намагається отримати вердикт через перший рівень.
+4. Якщо перший рівень не вдається, намагається отримати вердикт через другий рівень.
+5. Якщо другий рівень не вдається, використовується консервативний запасний варіант.
+6. Результати класифікації записуються в кеш.
 
-### Тестування
+## Публічний API
 
-Для unit-тестів зручно ін'єктувати:
+classify — Класифікує survived мутанти, перенаправляючи їх до CLOUD_MIN, якщо результат resolveModel дорівнює CLOUD_MIN, інакше до fallback.
 
-- `opts.client = { messages: { create: async () => ({ content: [{ text: '...' }] }) } }` — підставний клієнт.
-- `opts.cachePath = '/tmp/test-cache.json'` — ізольований кеш.
-- `opts.retryDelayMs = 0` — миттєві retries без `setTimeout`-блокувань.
+## Гарантії поведінки
 
-Файл `index.mjs` спроєктований так, що жодних інших залежностей мокати **не потрібно** — `cache.mjs`/`prompt.mjs`/`verdict-schema.mjs` мають детерміновану поведінку для тестів.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/scripts/coverage-classify/docs/verdict-schema.md

@@ -1,175 +1,30 @@
 ---
 docgen:
   source: npm/scripts/coverage-classify/verdict-schema.mjs
-  crc: 8a2c0df1
+  crc: ecf5dfe1
+  score: 100
 ---
 
 # verdict-schema.mjs
 
 ## Огляд
 
-Модуль `verdict-schema.mjs` визначає контракт даних для відповіді LLM-класифікатора в межах інструменту `coverage-classify`. Класифікатор приймає рішення про те, як трактувати вцілілого мутанта (surviving mutant) після прогону мутаційного тестування: чи варто на нього писати тест, чи він поведінково еквівалентний, чи це захисна гілка для неможливого стану, чи це склейка/обгортка, що покривається інтеграційними тестами.
+Файл надає схему `VerdictSchema` для валідації вердиктів LLM-класифікатора. Функція `parseVerdict` витягує JSON-об'єкт з сирої текстової відповіді моделі та перевіряє його відповідність визначеній схемі.
 
-Файл розв'язує дві задачі:
+## Поведінка
 
-1. Декларує **Zod-схему** `VerdictSchema`, якій має відповідати JSON-об'єкт-вердикт від LLM.
-2. Надає утиліту `parseVerdict`, яка приймає сирий текст відповіді LLM, витягує з нього перший знайдений JSON-блок, парсить його і валідовує за схемою.
+VerdictSchema
+Визначає схему для валідації вердикту LLM-класифікатора
 
-Призначення схеми — стабілізувати взаємодію з LLM: навіть якщо LLM повертає вердикт у вигляді тексту з преамбулою чи поясненнями, модуль робить «liberal-in, strict-out» — толерантно витягує JSON-острівець, а далі застосовує жорстку валідацію (категорія, межі впевненості, мінімальна осмисленість пояснення).
+parseVerdict
+Витягує JSON-об'єкт з текстової відповіді LLM і валідує його за схемою
 
-Категорії вердикту (`verdict`):
+## Публічний API
 
-- `worth-testing` — pure logic / реальні гілки, варто писати юніт-тест.
-- `equivalent` — мутант поведінково еквівалентний оригіналу, він не killable.
-- `defensive` — гілка для impossible state (захисний код), не killable.
-- `glue` — CLI entry / обгортка `runStandardRule` тощо; покривається інтеграційними тестами.
-- `wrapper` — тонкий `spawn`/`fetch`-обгортка; покривається інтеграційними тестами.
+VerdictSchema — Схема для структури вердикту.
+parseVerdict — Витягує JSON з тексту LLM і перевіряє його за схемою VerdictSchema.
 
-## Експорти / API
+## Гарантії поведінки
 
-Модуль експортує два символи (обидва — іменовані експорти ES modules):
-
-| Символ          | Тип                         | Призначення                                          |
-| --------------- | --------------------------- | ---------------------------------------------------- |
-| `VerdictSchema` | `ZodObject`                 | Схема валідації для verdict-об'єкта LLM.             |
-| `parseVerdict`  | `function(rawText: string)` | Парсер raw-text відповіді LLM у валідований verdict. |
-
-### `VerdictSchema`
-
-Z-об'єкт зі строго визначеними полями:
-
-- `verdict` — `z.enum(['worth-testing', 'equivalent', 'defensive', 'glue', 'wrapper'])`. Обов'язкове. Будь-яке інше значення відхиляється.
-- `confidence` — `z.number().min(0).max(1)`. Обов'язкове. Дробове число в діапазоні `[0, 1]`, де `0` — повна невпевненість, `1` — повна впевненість LLM у вердикті.
-- `reason` — `z.string().min(20).max(500)`. Обов'язкове. Текстове пояснення довжиною від 20 до 500 символів — мінімум змушує LLM аргументувати, максимум — обмежує балакучість.
-- `suggestedTest` — `z.string().max(300).optional()`. Опціональне. Текстова підказка/начерк тесту довжиною до 300 символів; за домовленістю заповнюється переважно для категорії `worth-testing`.
-
-Поля поза цим переліком не описано як заборонені на рівні схеми; за замовчуванням Zod пропускає невідомі ключі без помилки, але вони не з'являться в результаті типізації, що використовує цей модуль. Якщо в майбутньому потрібен strict-режим, його можна додати через `.strict()`.
-
-### `parseVerdict(rawText)`
-
-Високорівнева функція-фасад: «витягни JSON з тексту LLM і провалідуй».
-
-## Функції
-
-### `parseVerdict(rawText)`
-
-Сигнатура:
-
-```js
-function parseVerdict(rawText: string): {
-  verdict: 'worth-testing' | 'equivalent' | 'defensive' | 'glue' | 'wrapper',
-  confidence: number,
-  reason: string,
-  suggestedTest?: string
-}
-```
-
-Параметри:
-
-- `rawText` — `string`. Сирий текст, повернений LLM. Може містити довільний preamble/postamble навколо JSON-блоку (пояснення, markdown-загортки тощо). Очікується, що в тексті є рівно один корисний JSON-об'єкт-вердикт.
-
-Повертає:
-
-- Обʼєкт verdict, який пройшов валідацію `VerdictSchema`. Тип повернення відповідає схемі (див. вище).
-
-Side effects:
-
-- Жодних. Функція чиста: не пише в файлову систему, не звертається до мережі, не модифікує параметри.
-
-Алгоритм:
-
-1. Знайти позицію першого символу `{` через `rawText.indexOf('{')` → `jsonStart`.
-2. Знайти позицію останнього `}` через `rawText.lastIndexOf('}')` → `jsonEnd`.
-3. Якщо хоча б один з індексів дорівнює `-1` — кинути `Error('No JSON object found in LLM response')`.
-4. Інакше — вирізати підрядок `rawText.slice(jsonStart, jsonEnd + 1)` (включно з обома фігурними дужками) та віддати у `JSON.parse`.
-5. Результат парсингу передати у `VerdictSchema.parse(...)` і повернути.
-
-Виключення / помилки:
-
-- `Error('No JSON object found in LLM response')` — якщо в тексті немає жодної з фігурних дужок (`{` або `}`).
-- `SyntaxError` (від `JSON.parse`) — якщо вирізаний фрагмент не є валідним JSON. Наприклад, через зайвий текст усередині `{...}`, який LLM могла додати між дужками.
-- `ZodError` (від `VerdictSchema.parse`) — якщо JSON валідний, але не відповідає схемі: невідома категорія `verdict`, `confidence` поза `[0, 1]`, `reason` коротший за 20 символів або довший за 500, `suggestedTest` довший за 300 символів, відсутнє обов'язкове поле тощо.
-
-Поведінкові нюанси, важливі для викликача:
-
-- Стратегія «перший `{` … останній `}`» свідомо толерантна: дозволяє LLM писати щось ось так: `Here's the verdict: { ... } Hope it helps.` Однак якщо LLM повертає **кілька** JSON-обʼєктів, функція ризикує склеїти їх у невалідний фрагмент — це очікувано і впирається у валідацію JSON.
-- Функція не намагається «латати» некоректний JSON (немає trailing-comma-cleanup, немає markdown-fence-strip). Помилки прокидаються догори викликача — там і місце для retry / fallback-логіки.
-- У разі `ZodError` повідомлення зазвичай містить читабельний шлях до невалідного поля, що зручно для логування при debug LLM-промпта.
-
-## Залежності
-
-Зовнішні:
-
-- [`zod`](https://www.npmjs.com/package/zod) — рантайм-валідатор схем. Імпортується як `import { z } from 'zod'`. Версія керується кореневим `package.json` робочого простору `npm/`.
-
-Внутрішні:
-
-- Немає. Модуль не імпортує нічого з власного проєкту і не залежить від інших файлів `coverage-classify`.
-
-Стандартна бібліотека / середовище:
-
-- `JSON.parse` — глобальний API JavaScript runtime.
-- `String.prototype.indexOf` / `lastIndexOf` / `slice` — стандартні методи рядків.
-
-Цільове середовище: Node-сумісний рантайм (Node.js / Bun) із підтримкою ES Modules — файл написано як `.mjs`.
-
-## Потік виконання / Використання
-
-### Як модуль вписується в `coverage-classify`
-
-Інструмент `coverage-classify` працює за такою послідовністю (типова):
-
-1. Зчитати список вцілілих мутантів із результатів мутаційного тестування.
-2. Для кожного мутанта зібрати контекст (фрагмент коду, місце змін) та згенерувати промпт для LLM.
-3. Виконати запит до LLM і отримати raw-text відповідь.
-4. **Викликати `parseVerdict(rawText)`** із цього модуля, щоб отримати типізований verdict.
-5. Зберегти verdict у кеш / звіт (`apply.mjs`, `cache.mjs`) і застосувати дії: для `worth-testing` згенерувати TODO/тести, для решти — позначити мутант відповідною категорією.
-
-Таким чином, `verdict-schema.mjs` — це межа між «світом LLM» (нечіткий текст) і «світом інструменту» (структуровані дані).
-
-### Приклад використання
-
-```js
-import { parseVerdict, VerdictSchema } from './verdict-schema.mjs'
-
-// 1) Парсимо raw-відповідь LLM
-const rawLLM = `
-The mutant is in a defensive branch. Here is the verdict:
-{
-  "verdict": "defensive",
-  "confidence": 0.92,
-  "reason": "The condition guards an impossible state when the input list is empty.",
-  "suggestedTest": ""
-}
-Thanks!
-`
-
-try {
-  const verdict = parseVerdict(rawLLM)
-  // verdict.verdict === 'defensive'
-  // verdict.confidence === 0.92
-  console.log(verdict)
-} catch (err) {
-  // 'No JSON object found in LLM response' | SyntaxError | ZodError
-  console.error('LLM verdict invalid:', err.message)
-}
-
-// 2) Якщо в нас уже є об'єкт (наприклад, з кешу) — валідуємо безпосередньо через схему
-const cached = { verdict: 'glue', confidence: 1, reason: 'CLI entry point only, integration covers.' }
-const ok = VerdictSchema.parse(cached) // кине ZodError, якщо не відповідає
-```
-
-### Граничні випадки
-
-- Порожній рядок → `indexOf('{') === -1` → кидаємо `'No JSON object found in LLM response'`.
-- Рядок без `}` (LLM обірвалась) → `lastIndexOf('}') === -1` → та сама помилка.
-- LLM повернула markdown-fence (` ```json ... ``` `) навколо JSON → `parseVerdict` витягне саме JSON-острів між першим `{` і останнім `}`, fence ігнорується.
-- LLM повернула `confidence: 1.5` → `ZodError` (порушено `max(1)`).
-- LLM повернула `verdict: 'unknown'` → `ZodError` (не входить у `z.enum([...])`).
-- LLM повернула `reason` коротшим за 20 символів → `ZodError` (`min(20)`). Це навмисний захист від відповідей-однословів типу `"ok"`.
-
-### Рекомендації для викликача
-
-- Обгортайте виклик `parseVerdict` у `try/catch` і за помилки робіть retry з посиленим промптом (наприклад, з нагадуванням про схему) або падайте у fallback-категорію.
-- Не зберігайте у кеш `rawText` як вердикт — зберігайте лише провалідований об'єкт (результат `parseVerdict`); це підтримує інваріант «у кеші тільки валідні дані».
-- Якщо в майбутньому з'являться нові категорії — оновлюйте `z.enum` тут, інакше LLM-вердикти з новими значеннями будуть відхилятися.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/scripts/dispatcher/docs/trace.md

@@ -0,0 +1,35 @@
+---
+docgen:
+  source: npm/scripts/dispatcher/trace.mjs
+  crc: 8d541669
+  score: 100
+---
+
+# trace.mjs
+
+## Огляд
+
+Файл забезпечує наскрізну простежуваність артефактів. Він читає front-matter з директорій `docs/{tasks,specs,plans,adr}`, будує ланцюг за лінками та позначає розриви. Функції генерують аналіз, який потім рендериться у текстовий вивід, а трасування виконується для зчитування артефактів.
+
+## Поведінка
+
+parseFrontMatter Парсить плаский YAML-front-matter. Не обробляє вкладеність. Відрізає інлайн-коментарі.
+
+analyze Будує аналіз. Для кожного артефакту генерує лінки з позначкою про розрив.
+
+render Текстовий рендер аналізу. Форматує вивід для читання.
+
+runTraceCli Виконує трасування. Зчитує артефакти з директорій. Будує аналіз. Повертає код виходу.
+
+## Публічний API
+
+parseFrontMatter — Парсить плаский YAML-front-matter (key: value). Обробляє лише основні поля spec/plan/task-record. Видаляє інлайн-коментарі.
+analyze — Створює аналіз: для кожного артефакту — зв'язок його лінків зі статусом ok/розрив. `breaking` означає відсутність лінка, що руйнує ланцюг.
+render — Відображає текстовий вивід аналізу.
+runTraceCli — Виконує команду CLI `n-cursor trace [--json]`. Повертає 1, якщо виявлено розриви ланцюга.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.