v2.3.0 — Wizard-only release

README.md

@@ -4,7 +4,7 @@
 
 Скилл для Claude, который превращает неструктурированное описание процесса в читаемую BPMN 2.0 схему (Camunda 7, Platform) и — по запросу — в Excel-спецификацию, сверенную со схемой.
 
-**Версия:** 2.2.0
+**Версия:** 2.3.0
 **Автор:** Andrey Zagreev — [@zagreev](https://t.me/zagreev)
 **Лицензия:** [MIT](#лицензия)
 **Целевая платформа:** Camunda 7 (Platform)
@@ -70,9 +70,39 @@
 - «Вот описание процесса, нужна диаграмма с пулами»
 - «Преврати это в .bpmn файл»
 - «Нужна Excel-таблица по этому BPMN»
+- «Уточни процесс перед моделированием»
+- «Обнови существующий BPMN»
+- «Дополни BPMN»
+- «Расширь схему»
+- «Генерируй с допущениями»
 
 Не сработает на запросах про UML, sequence-диаграммы, ER-диаграммы, Mermaid, Excalidraw — у них своя специфика.
 
+В v2.3.0 режим по-прежнему один — Generate. Вход может быть двух типов:
+- **Text-only**: обычное описание процесса → Clarification Wizard → генерация новой BPMN-схемы.
+- **Mixed input**: текст + существующий `.bpmn` / XML → Generate with reuse-ID → сохранение прежних ID там, где смысл узлов не изменился.
+
+## Clarification Wizard
+
+Clarification Wizard — шаг перед генерацией BPMN. Он ищет недостающие факты по 6 категориям: topology, participants, happy_path, exception_paths, slas, data_ownership.
+
+Если пробелов нет, скилл сообщает «Всё понятно, перехожу к генерации». Если не хватает 1–5 фактов, задаёт короткие вопросы в приоритетном порядке. Если данных слишком мало или пользователь пишет «генерируй с допущениями», скилл продолжает без интервью и явно помечает принятые defaults через `⚠ Допущение:`.
+
+Подробные правила: [`references/clarification-wizard.md`](references/clarification-wizard.md).
+
+## Update scenario
+
+Если пользователь прикладывает существующий BPMN/XML и просит «обнови», «дополни», «измени» или «расширь существующий», скилл работает как Generate with reuse-ID.
+
+Правила:
+- неизменившиеся узлы сохраняют старые ID;
+- переименованные узлы с тем же типом и смыслом сохраняют ID;
+- новые узлы получают новые ID;
+- при смене типа, например `task` → `userTask`, старый ID не переиспользуется;
+- после генерации выводится diff-summary относительно исходного BPMN.
+
+Подробные правила: [`references/reuse-id-rules.md`](references/reuse-id-rules.md).
+
 ## Требования
 
 **Обязательно:**
@@ -115,8 +145,10 @@
 
 ## Как работает внутри (9 шагов)
 
+0. **Классификация входа** — text-only, mixed input, zeebe namespace, unsupported format или invalid XML
 1. **Загрузка документации Camunda** через MCP — синтаксис BPMN, extension-элементы, паттерны пулов, аннотации, сабпроцессы
-2. **Классификация входа** — отрасль, участники, активности, события, шлюзы, артефакты
+1.5. **Clarification Wizard** — уточнение недостающих фактов или явные `⚠ Допущение:` annotations
+2. **Классификация процесса** — отрасль, участники, активности, события, шлюзы, артефакты
 3. **Выбор топологии** по правилу: несколько организаций → collaboration с пулами; один бизнес с ролями → пул с лэйнами; один актёр → плоский процесс
 4. **Выбор декомпозиции** по правилу 7±2: больше 9 узлов или 2+ уровня вложенных шлюзов → overview + drill-down подпроцессы
 5. **Генерация BPMN XML** в UTF-8, с русскими подписями, BPMN DI, Camunda extensions, текстовыми аннотациями для SLA / регуляторки / открытых вопросов
@@ -144,6 +176,9 @@ bpmn-process-modeler/
     │   ├── public-sector-patterns.md    — государственная услуга (ФЗ-210)
     │   └── it-ops-patterns.md           — incident management, change management
     ├── annotation-style-guide.md        — когда использовать textAnnotation + шаблоны фраз на русском; отдельный подраздел про особенности аннотирования шлюзов (XOR / OR / event-based / parallel, default flow, FEEL-condition, вынесение логики в DMN)
+    ├── clarification-wizard.md          — правила Wizard: missing-facts categories, вопросы, assumption mode
+    ├── input-classification.md          — Step 0 routing: text-only, mixed input, rejects, invalid XML
+    ├── reuse-id-rules.md                — правила сохранения ID при обновлении существующего BPMN
     ├── validation-checklist.md          — 7 блокирующих проверок XML с Python-кодом + 10 рекомендательных best practices (на основе Camunda bpmnlint и docs)
     ├── excel-spec-template.md           — 9-колоночный шаблон + worked example на BNPL
     └── reconciliation-procedure.md      — 9 проверок сверки Excel и BPMN с openpyxl-кодом
@@ -217,6 +252,17 @@ bpmn-process-modeler/
 
 ## Changelog
 
+### v2.3.0 — дата релиза TBD
+
+Wizard-only minor release.
+
+- Добавлен Step 0 input classification: text-only, mixed input, Camunda 8 / `zeebe:*` reject, unsupported formats, invalid XML recovery/reject.
+- Добавлен Clarification Wizard: 6 missing-facts categories, приоритет вопросов, hard limit 5 вопросов, режим генерации с допущениями.
+- Добавлен Update scenario для text + existing BPMN/XML: Generate with reuse-ID и diff-summary после генерации.
+- Validation checklist получил 5-level severity taxonomy: ERROR / TASK / REVIEW / WARNING / INFO.
+- Добавлен новый annotation prefix `⚠ Допущение:` отдельно от `⚠ Уточнить:`.
+- Excel template расширен листом «Допущения» для review принятых defaults.
+
 ### v2.2.0 — 26 апреля 2026
 
 Rules and release-notes alignment patch.

RELEASE.md

@@ -28,6 +28,28 @@ Release tags must be signed with an SSH signing key registered on the releasing
 
 ## Pre-release checklist
 
+### v2.3.0 — release date TBD
+
+Release scope:
+- Step 0 input classification
+- Clarification Wizard
+- Mixed input / Update scenario with reuse-ID
+- 5-level severity documentation
+- «Допущения» sheet in Excel template
+
+Required local checks:
+- `pytest tests/release/test_input_classification.py -v`
+- `pytest tests/release/test_wizard.py -v`
+- `pytest tests/release/test_mixed_input.py -v`
+- Snapshot freshness check passes: `snapshot_expiry=2026-10-23`, 179 days after 2026-04-27
+
+New v2.3.0 test modules:
+- `tests/release/test_input_classification.py`
+- `tests/release/test_wizard.py`
+- `tests/release/test_mixed_input.py`
+
+General checklist:
+
 1. Start from a clean `main` synchronized with `origin/main`.
 2. Create a release branch, for example `release/v2.0.2`.
 3. Make only release-scope changes: version, changelog, tests, CI, packaging, and release documentation.

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: bpmn-process-modeler
-description: Converts unstructured text descriptions of business processes (meeting transcripts, written narratives, process memos) into valid BPMN 2.0 XML for Camunda Platform 7, with all diagram labels in Russian and optional Excel process specification. Use whenever the user pastes a transcript, meeting notes, or prose describing a business process and asks to model, draw, map, diagram, or convert it into BPMN, Camunda, a .bpmn file, pools and lanes, or a process XML. Also use when the user wants an Excel specification table of a BPMN process. The skill pre-loads current Camunda documentation via the Camunda MCP server (search_camunda_knowledge_sources) before generating XML, validates the result against 7 structural and language checks, asks the user for approval, then optionally exports a 9-column UTF-8 Excel specification reconciled against the diagram across 9 parity checks.
-version: 2.2.0
+description: Converts prose, transcripts, notes, process memos, or mixed text + existing BPMN into valid BPMN 2.0 XML for Camunda Platform 7, with Russian labels and optional Excel specification. Use when the user asks to model, draw, map, diagram, convert to BPMN/Camunda/.bpmn/XML, create pools and lanes, export an Excel process table, уточни процесс перед моделированием, обнови существующий BPMN, дополни BPMN, расширь схему, or генерируй с допущениями. The skill classifies input, loads Camunda docs, runs the Wizard when needed, validates XML, asks for approval, then exports a reconciled UTF-8 Excel specification.
+version: 2.3.0
 snapshot_version: 1.0
 snapshot_date: 2026-04-26
 snapshot_expiry: 2026-10-23
@@ -34,7 +34,34 @@ Violating any of these means the deliverable is broken. Treat them as preconditi
 
 ---
 
-## The workflow — 9 steps in fixed order
+## The workflow — Generate mode in fixed order
+
+### Step 0 — Input classification
+
+Classify the user input before loading Camunda knowledge or generating XML. Use
+`references/input-classification.md` as the routing source of truth.
+
+Route pure text to Generate, mixed text + BPMN/XML to Generate with reuse-ID,
+Camunda 8 / `zeebe:*` XML to REJECT with Diagram Converter guidance, unsupported
+formats to REJECT, and invalid XML to RECOVER or REJECT with the parse error.
+
+#### Update scenario (mixed input)
+
+When Step 0 detects mixed input (text + .bpmn), workflow becomes:
+
+1. Step 0: detected as mixed input
+2. Reuse-ID extraction: parse old BPMN, build ID index
+3. Step 1: Camunda knowledge load (unchanged)
+4. Step 1.5: Wizard runs only on new/changed parts (per `references/reuse-id-rules.md`)
+5. Steps 2-9: generate new BPMN preserving existing IDs where appropriate
+6. Output:
+   - Final BPMN (with reused + new IDs)
+   - Excel spec (per existing template, +«Допущения» sheet if applicable)
+   - Diff-summary text block (see reuse-id-rules.md)
+
+**Cross-references:**
+- `references/reuse-id-rules.md` — full ID reuse rules
+- `references/clarification-wizard.md` — Wizard behavior in Update scenario
 
 ### Step 1 — Load current Camunda documentation (with fallback)
 
@@ -68,6 +95,33 @@ At top of generated XML:
 
 **In degraded mode (Option B):** proceed with the full workflow (Steps 2-9) as normal, but flag the degraded status in Step 7 approval prompt (see Step 7).
 
+### Step 1.5 — Clarification Wizard
+
+Run the Wizard after Camunda knowledge is available and before parsing the
+process into BPMN elements. Use `references/clarification-wizard.md` as the
+source of truth.
+
+Branching:
+- If 0 missing facts are detected: skip Wizard, inform user "Всё понятно, перехожу к генерации", proceed to Step 2.
+- If 1-5 missing facts are detected: ask targeted questions in priority order, then proceed to Step 2.
+- If 6+ missing facts are detected: offer more detail or "with assumptions" mode, then proceed to Step 2.
+
+Assumption mode trigger phrases include "делай с допущениями", "генерируй с предположениями", "не задавай вопросов", "as is", "as-is", and "just do it".
+
+#### Discipline rules for Wizard (Step 1.5)
+
+**Do NOT:**
+- Ask questions when answer is in the source text (anti-hallucination)
+- Mark as `⚠ Допущение:` what is trivially derivable (e.g., task type from verb)
+- Ask more than 5 questions in one pass
+- Skip Wizard silently — always inform user "Всё понятно, перехожу к генерации"
+
+**Do:**
+- Detect all 6 categories before deciding routing
+- Respect priority order (topology first, data_ownership last)
+- Use category default if user skips ("не знаю / пропустить")
+- Mark every accepted assumption with `⚠ Допущение:` annotation + Excel row
+
 ### Step 2 — Parse and classify the input
 
 Extract and state explicitly before modeling:

references/annotation-style-guide.md

@@ -351,4 +351,47 @@ Camunda: "Avoid naming event-based gateways; avoid naming parallel gateways and
 
 ---
 
+## Annotation prefix: ⚠ Допущение:
+
+Distinct from `⚠ Уточнить:` — used by Clarification Wizard for model-accepted assumptions.
+
+### Comparison
+
+| Prefix | When to use | Who fills |
+|---|---|---|
+| `⚠ Уточнить:` | Source has a gap or ambiguity that the model cannot resolve | Model leaves question to user |
+| `⚠ Допущение:` | Model has filled missing information using typical practice defaults | Model explicitly marks its choice |
+| `Примечание:` | Informational comment without call to action | For context only |
+
+### Rules for `⚠ Допущение:`
+
+1. Use only when the Wizard has accepted a missing fact via "with assumptions" mode OR when user skipped a Wizard question
+2. Always pair with `<bpmn:association>` linking annotation to target node
+3. Annotation text format: two lines minimum
+   - Line 1: `⚠ Допущение: <what was assumed>`
+   - Line 2+: justification ("В исходнике не указано / принято по типичной практике / etc.")
+4. ID format: `TextAnnotation_Assumption_<N>` where N is sequential per process
+
+### XML example
+
+```xml
+<bpmn:textAnnotation id="TextAnnotation_Assumption_3">
+  <bpmn:text>⚠ Допущение: SLA на ручную проверку — 24 часа.
+В исходнике срок не указан, принят по типичной банковской практике.</bpmn:text>
+</bpmn:textAnnotation>
+
+<bpmn:association id="Association_Assumption_3"
+  sourceRef="Activity_Manual_Review"
+  targetRef="TextAnnotation_Assumption_3"/>
+```
+
+### When NOT to mark as Допущение
+
+- Trivially derivable from context (task type from verb)
+- Standard BPMN conventions (start event begins process)
+- Explicitly stated facts in the source text
+- Meta-information about model's working approach
+
+---
+
 **Этот гайд обязателен к использованию в Step 5 (генерация XML) и Step 6 (валидация).** Если аннотация в модели отклоняется от шаблонов и правил этого документа — это WARN при валидации, требующий либо коррекции, либо явного обоснования в отчёте.