@nitra/cursor 1.13.1 → 1.13.2

package/.claude-template/hooks/capture-decisions.sh

@@ -83,33 +83,51 @@ if [[ -z "$TRANSCRIPT" ]]; then
 fi
 
 PROMPT=$(cat <<'EOF'
-You analyze a Claude Code session transcript and produce a durable knowledge artifact (ADR, Runbook, or Knowledge note) capturing what was done and why.
+You analyze an AI coding session transcript and produce durable decision documentation.
 
-LANGUAGE: Write the ENTIRE output in Ukrainian. This applies to the title, all section content, prose, and rationale. Keep code identifiers, file paths, commands, and tool or library names in their original form (do not translate `walkDir`, `package.json`, `npm`, etc.) — only translate the natural-language prose around them. Section labels themselves stay in Ukrainian per the template below.
+LANGUAGE: Write the content in Ukrainian. Keep MADR section headings in English exactly as shown below. Keep code identifiers, file paths, commands, and tool or library names in their original form (do not translate `walkDir`, `package.json`, `npm`, etc.).
 
 IMPORTANT: by "decision" we mean the design choice expressed in the session — even if the user pre-specified it in their brief. The user dictating the approach IS the decision; capture it, including the rationale they gave or that became apparent during implementation. Do NOT return NONE just because the user gave detailed instructions upfront.
 
+ANTI-HALLUCINATION RULES:
+- Use only facts present in the transcript, tool calls, changed file paths, or direct implications of those facts.
+- Do not invent decision makers, stakeholders, business context, requirements, alternatives, or consequences.
+- If alternatives were not discussed, write exactly: "Інші варіанти в transcript не обговорювалися."
+- If a consequence is unknown, write it as "Neutral, because transcript не містить підтвердження наслідку."
+- Prefer specific file paths and commands from the transcript over generic prose.
+
 OUTPUT RULES:
 - Emit one or more markdown blocks in this exact shape (no preamble, no trailing prose):
 
-## [ADR|Runbook|Knowledge] <короткий заголовок українською>
-**Контекст:** <яка проблема / ситуація це спричинила — 1-2 речення>
-**Рішення/Процедура/Факт:** <що було зроблено — конкретно: змінені файли, введена семантика, кроки>
-**Обґрунтування:** <чому саме такий підхід — з ТЗ користувача або міркувань асистента>
-**Розглянуті альтернативи:** <перелік явно обговорених, або «не обговорювалися»>
-**Зачіпає:** <файли, модулі, публічні API, конфіги>
+## ADR <короткий заголовок українською>
+
+## Context and Problem Statement
+<1-3 речення: яка проблема / ситуація спричинила рішення.>
+
+## Considered Options
+* <назва явно обговореного варіанта>
+* <або "Інші варіанти в transcript не обговорювалися.">
+
+## Decision Outcome
+Chosen option: "<назва обраного варіанта>", because <коротке обґрунтування з transcript>.
+
+### Consequences
+* Good, because <підтверджений позитивний наслідок або "transcript фіксує очікувану користь: ...">.
+* Bad, because <підтверджений негативний наслідок або "transcript не містить підтверджених негативних наслідків.">.
+
+## More Information
+<файли, команди, публічні API, конфіги, transcript facts. Якщо нема — "Додаткової інформації в transcript не зафіксовано.">
 
 WHEN TO PICK EACH TYPE:
-- ADR: a design choice (library, schema, pattern, semantics of a field/API). Most substantive code work qualifies.
-- Runbook: a procedure to operate, fix, deploy, or reproduce something.
-- Knowledge: a non-obvious constraint, gotcha, or invariant uncovered (without a corresponding code change).
+- Emit ADR for design choices: library, schema, pattern, file layout, hook semantics, API behavior, validation semantics.
+- Do not emit Runbook or Knowledge blocks here. This hook stores MADR-style decision records only.
 
 OUTPUT NONE ONLY IF the session is genuinely trivial:
 - A single typo fix, comment edit, or lint cleanup with no design content
-- A pure question/answer with no code change and no surprising fact
+- A pure question/answer with no durable decision
 - An aborted/empty session
 
-When in doubt, emit a block. Capturing too much is acceptable; missing real work is not.
+When in doubt, emit a conservative ADR with explicit "not discussed" placeholders rather than inventing missing details.
 
 TRANSCRIPT FOLLOWS:
 ---

package/.claude-template/hooks/normalize-decisions.sh

@@ -160,7 +160,7 @@ PROMPT_HEADER=$(cat <<'EOF'
 {
   "operations": [
     { "op": "delete",     "file": "<basename>.md", "reason": "..." },
-    { "op": "rewrite",    "file": "<basename>.md", "slug": "<kebab-case-ukrainian>", "content": "<повний markdown файлу>" },
+    { "op": "rewrite",    "file": "<basename>.md", "slug": "<kebab-case-ukrainian>", "content": "<повний markdown файлу у MADR 4.0.0>" },
     { "op": "merge-into", "file": "<basename>.md", "target": "<slug>.md", "additions": "<markdown для дописування>" }
   ]
 }
@@ -169,11 +169,15 @@ PROMPT_HEADER=$(cat <<'EOF'
 
 1. `delete` — драфт тривіальний / повністю покритий іншим існуючим clean-ADR-ом / порожній. Поясни короткою причиною українською.
 
-2. `rewrite` — драфт має самостійну цінність. Повертай у `content` повний фінальний вміст файлу:
+2. `rewrite` — драфт має самостійну цінність як decision record. Повертай у `content` повний фінальний вміст файлу у форматі MADR 4.0.0 minimal:
    - Без YAML frontmatter (жодного `session:`, `captured:`, `transcript:`).
    - Заголовок `# <Title>` українською.
    - Один рядок `**Status:** Accepted` і один рядок `**Date:** YYYY-MM-DD` — дату беремо з поля `captured:` оригінальної чернетки (перші 10 символів ISO-дати).
-   - Далі розділи **Контекст**, **Рішення/Процедура/Факт**, **Обґрунтування**, **Розглянуті альтернативи**, **Зачіпає** — як у драфті, але причесані: цілісні речення, без скорочень, без слідів автогенерованого тегу типу `## Knowledge`.
+   - Далі секції з точними MADR headings англійською: `## Context and Problem Statement`, `## Considered Options`, `## Decision Outcome`, `### Consequences`, `## More Information`.
+   - У `## Considered Options` перелічуй лише варіанти, які є в драфті/transcript. Якщо альтернатив не було, додай bullet `Інші варіанти в transcript не обговорювалися.`
+   - У `## Decision Outcome` використовуй форму `Chosen option: "<option>", because <reason>.` Причина має спиратися на драфт/transcript, без вигаданого business/context.
+   - У `### Consequences` пиши bullets `Good, because ...`, `Bad, because ...`, `Neutral, because ...`. Якщо наслідок не зафіксований, явно пиши `transcript не містить підтвердження ...`, не вигадуй.
+   - У `## More Information` перенеси файли, команди, публічні API, конфіги й transcript facts. Якщо нема — `Додаткової інформації в transcript не зафіксовано.`
    - `slug` — kebab-case українською (наприклад `ланцюжок-запуску-abie`, `npm-publish-flow`). Без розширення `.md`. Літери малі, дозволено цифри, дефіс, кирилиця. Якщо тема технічна англійською (назва пакету, ключове слово) — лиши англійською без транслітерації.
 
 3. `merge-into` — драфт повторює тему вже існуючого clean-файлу зі списку нижче. `target` — точна назва файлу зі списку (з `.md`). `additions` — лише новий зміст, який варто дописати в кінець target-файлу під підзаголовком `## Update YYYY-MM-DD` (date з `captured` драфта). Якщо нічого нового додати — використовуй `delete`.
@@ -184,6 +188,7 @@ PROMPT_HEADER=$(cat <<'EOF'
 - Кожен файл з вхідного списку має зʼявитися у `operations` рівно один раз.
 - Слаги не повторювати між операціями того самого батча. Якщо дві чернетки про одну тему — одна `rewrite`, інша `merge-into target: <slug>.md` з тим самим slug-ом.
 - Не вигадуй target, якого нема у списку clean-файлів.
+- Не вигадуй альтернативи, decision drivers, наслідки, людей або зовнішній контекст. Якщо даних бракує — явно напиши, що transcript цього не містить.
 
 Вхідні драфти і clean-список — нижче.
 EOF

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.2] - 2026-05-17
+
+### Changed
+
+- **`adr` hook output тепер MADR v4.0.0 minimal** — capture/normalize prompts генерують ADR-и з canonical headings `Context and Problem Statement`, `Considered Options`, `Decision Outcome`, `Consequences`, `More Information`. Prompts стали evidence-bound: якщо transcript не містить альтернатив або підтверджених наслідків, hook явно пише, що даних немає, замість вигадування деталей.
+
 ## [1.13.1] - 2026-05-17
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.13.1",
+  "version": "1.13.2",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/adr/adr.mdc

@@ -4,9 +4,19 @@ alwaysApply: true
 version: '2.0'
 ---
 
-## Дві фази, один каталог
+## MADR v4 і дві фази
 
-ADR живуть у єдиному каталозі **`docs/adr/`**. Є два стани файлу, які відрізняються YAML frontmatter:
+ADR живуть у єдиному каталозі **`docs/adr/`**. Clean ADR-и мають формат **MADR v4.0.0 minimal** з точними section headings англійською:
+
+- `## Context and Problem Statement`
+- `## Considered Options`
+- `## Decision Outcome`
+- `### Consequences`
+- `## More Information`
+
+Вміст секцій — українською, code identifiers / paths / commands — як у transcript. Якщо transcript не містить альтернатив або підтверджених наслідків, hook має явно писати `Інші варіанти в transcript не обговорювалися.` або `transcript не містить підтвердження ...`, а не вигадувати відсутні факти.
+
+Є два стани файлу, які відрізняються YAML frontmatter:
 
 - **Draft** — файл з frontmatter `session: …`, `captured: …`, `transcript: …` та timestamp-іменем `YYYYMMDD-HHMMSS-<sid>.md`. Пише `capture-decisions.sh` після кожної сесії.
 - **Clean** — файл без frontmatter, з kebab-case-іменем `<slug>.md` (наприклад `ланцюжок-запуску-abie.md`). Створює `normalize-decisions.sh` або людина руками.
@@ -15,7 +25,7 @@ ADR живуть у єдиному каталозі **`docs/adr/`**. Є два
 
 ### Фаза 1 — Capture
 
-Stop-hook `capture-decisions.sh` зчитує JSONL-транскрипт сесії (через `jq`), витягає текст, `thinking`-блоки та назви `tool_use`-викликів, передає компактний дайджест у LLM CLI з промптом українською і записує результат у **`docs/adr/<timestamp>-<session>.md`**, якщо модель повернула блок з шапкою `## ADR|Runbook|Knowledge …`. Якщо модель повернула `NONE` (тривіальна сесія) — нічого не пишеться. Рекурсію з внутрішнього виклику моделі блокує env-var `CAPTURE_DECISIONS_RUNNING=1`.
+Stop-hook `capture-decisions.sh` зчитує JSONL-транскрипт сесії (через `jq`), витягає текст, `thinking`-блоки та назви `tool_use`-викликів, передає компактний дайджест у LLM CLI з evidence-bound промптом і записує результат у **`docs/adr/<timestamp>-<session>.md`**, якщо модель повернула MADR-блок з шапкою `## ADR …`. Якщо модель повернула `NONE` (тривіальна сесія) — нічого не пишеться. Рекурсію з внутрішнього виклику моделі блокує env-var `CAPTURE_DECISIONS_RUNNING=1`.
 
 Для Cursor payload скрипт бере `transcript_path`, `conversation_id` / `generation_id` і `workspace_roots[0]`; для Claude Code — `transcript_path`, `session_id` і `CLAUDE_PROJECT_DIR`.
 
@@ -34,7 +44,7 @@ LLM повертає масив операцій:
 | `op` | Семантика | Поля |
 | --- | --- | --- |
 | `delete` | Чернетка тривіальна / повністю покрита іншим clean-ADR-ом. | `file`, `reason` |
-| `rewrite` | Чернетка стає окремим clean-файлом: frontmatter знімається, ім'я → `<slug>.md`, додаються `**Status: Accepted**` і `**Date:**` з `captured`. | `file`, `slug`, `content` |
+| `rewrite` | Чернетка стає окремим clean-файлом MADR v4 minimal: frontmatter знімається, ім'я → `<slug>.md`, додаються `**Status:** Accepted`, `**Date:**` з `captured` і canonical MADR headings. | `file`, `slug`, `content` |
 | `merge-into` | Чернетка повторює тему вже існуючого clean-файлу; дописуємо `## Update YYYY-MM-DD` у кінець `target`. | `file`, `target`, `additions` |
 
 `slug` — kebab-case українською (`ланцюжок-запуску-abie`, `npm-publish-flow`); англійські технічні терміни лишаються англійською без транслітерації. Колізія slug-ів обробляється детермінованим суфіксом `-2`, `-3`.