@zrg-sh/studio 0.1.0

package/template/product-specs/rules/docs-conventions.md

@@ -0,0 +1,81 @@
+---
+paths:
+  - "docs/**"
+---
+
+# Documentation conventions
+
+## File naming
+- Файлы: kebab-case на английском (`business-rules.md`, `ubiquitous-language.md`)
+- Папки доменов: kebab-case (`training-session`, `scenario-catalog`)
+- Change packages: `PRDCT-XXXX` (четырёхзначный номер)
+- НЕ называть файлы `index.md` — Obsidian graph показывает имя файла. Используй осмысленные имена (`domains-dashboard.md`, `changes-dashboard.md`)
+- Файлы внутри PRDCT-папок: по шаблону (`01-discovery.md`, `02-product-spec.md`, ...)
+
+## Heading hierarchy
+- H1 (`#`) — только один на файл, название документа
+- H2 (`##`) — основные секции
+- H3 (`###`) — подсекции
+- H4+ — не использовать без необходимости
+
+## YAML frontmatter (ОБЯЗАТЕЛЬНО)
+Каждый .md файл в docs/ ДОЛЖЕН иметь frontmatter:
+```yaml
+---
+type: domain | change | adr | meta | aggregate | events | invariants | business-rules | ubiquitous-language | integrations | ownership | index
+domain: training-session    # если файл относится к домену
+status: draft | active | accepted | deprecated
+tags:
+  - domain/training-session  # nested tag = домен
+  - aggregate               # тип документа
+owner: team-name
+created: YYYY-MM-DD
+---
+```
+
+## Tags (nested hierarchy)
+```
+#domain/<name>              — принадлежность к домену
+#change/PRDCT-XXXX           — принадлежность к change package
+#status/<state>             — текущий статус
+#adr/ADR-XXX               — ссылка на ADR
+#aggregate, #event, #invariant, #business-rule — тип документа
+```
+
+## Links & references
+- Между документами vault: wikilinks `[[path/to/file]]`
+- Внешние URL: markdown `[text](https://url)`
+- Embeds (встраивание содержимого): `![[file]]`
+- Block references: `[[file#^block-id]]`
+
+## Callouts (семантическая разметка)
+- `> [!danger]` — инварианты (НЕЛЬЗЯ нарушить)
+- `> [!warning]` — corner cases, breaking changes, риски
+- `> [!info]` — business rules, контекст, пояснения
+- `> [!bug]` — edge cases, известные проблемы
+- `> [!question]` — открытые вопросы
+- `> [!tip]` — рекомендации, живые дашборды
+- `> [!example]` — примеры использования
+
+## Mermaid diagrams
+- `stateDiagram-v2` — в aggregates.md (state machine агрегата)
+- `erDiagram` — в aggregates.md (структура данных)
+- `sequenceDiagram` — в events.md (flow событий между consumers)
+- `graph` — в integrations.md (карта upstream/downstream зависимостей)
+- `mindmap` — в capability-map.md (дерево возможностей)
+- `gantt` — в rollout.md (таймлайн раскатки)
+
+## Dataview queries
+- Для живых дашбордов в index/dashboard файлах
+- Запросы строятся по frontmatter полям (type, domain, status, tags)
+- НЕ дублировать данные руками — если можно собрать dataview, собирай dataview
+
+## Tables
+- Всегда с заголовками
+- Пустые ячейки: `—` (не пусто)
+
+## Status tracking
+- Статус документа: в frontmatter `status:` И в metadata.yaml для change packages
+- Допустимые статусы change: `draft | discovery | spec | analysis | in-progress | done`
+- Допустимые статусы domain: `draft | active | deprecated`
+- Допустимые статусы ADR: `proposed | accepted | deprecated | superseded`

package/template/product-specs/rules/domain-conventions.md

@@ -0,0 +1,69 @@
+---
+paths:
+  - "product-specs/docs/domains/**"
+---
+
+# Domain modeling rules
+
+## Aggregate rules
+- Агрегат = граница консистентности
+- Один агрегат — одна транзакция
+- Ссылки между агрегатами — только по ID
+- Если данные нужны из другого домена — это ref, а не вложение
+
+### Здоровье агрегатов (не лимиты, а сигналы)
+- 0 агрегатов в домене → это не домен, а словарь. Не создавай домен без агрегата
+- Количество агрегатов не ограничено — 50 норм если каждый имеет чёткую ответственность
+- **God-aggregate detector:** если агрегат имеет > 15 полей или > 7 состояний → задать вопрос: "Это точно один агрегат или тут два склеенных?"
+- Агрегат с 1 полем → скорее всего value object, а не агрегат
+- **Ключевой тест:** можно ли объяснить ответственность агрегата одним предложением? Если нет — разбивать
+
+## Ubiquitous language
+- Каждый термин определён ровно в одном домене
+- Forbidden synonyms — жёстко, нельзя использовать нигде
+- Conflicts with — задокументировать, если термин значит другое в другом домене
+
+## Business rules
+- Бизнес-правило = правило с возможными исключениями и edge cases
+- Каждое правило ОБЯЗАНО иметь: rationale (зачем), source (откуда), edge cases
+- Правило без rationale — это не правило, а догадка. Удалить или добавить rationale
+
+### Здоровье business rules
+- 0 правил в домене → домен не проработан. Минимум бизнес-логика существует
+- Количество не ограничено — 100 правил в домене billing это нормально
+- **Тест качества:** правило проверяемое? Можно написать тест? Если нет — переформулировать
+- **Дубликат-детектор:** два правила говорят одно и то же разными словами → объединить
+- **Orphan-детектор:** правило без ссылки на PRDCT/DMNPRDCT → откуда взялось? Добавить source
+
+## Invariants
+- Инвариант = правило, которое НИКОГДА не может быть нарушено
+- Отличие от business rule: бизнес-правило может иметь исключения, инвариант — нет
+- Формулировка: утвердительная (`Session всегда привязана к Learner ID`)
+
+### Здоровье invariants
+- 0 инвариантов → домен не имеет constraints? Невозможно. Минимум 1 инвариант
+- **Тест:** если инвариант нарушен — система сломана? Если нет — это business rule, не инвариант
+- **Конфликт-детектор:** два инварианта противоречат друг другу → критическая проблема
+
+## Events
+- Формат: PastTense (`SessionStarted`, `TurnCompleted`)
+- Payload: минимально необходимый набор данных
+- Гарантии: at-least-once по умолчанию
+- Idempotency: всегда указывать ключ идемпотентности
+
+### Здоровье events
+- Event без consumer → orphan. Зачем генерируем то что никто не слушает?
+- Event без producer → ghost. Кто его вообще отправляет?
+- **Payload bloat:** если payload > 10 полей → скорее всего протекает внутренняя структура агрегата. Payload = минимум для consumer
+- **Cross-domain event:** если event пересекает домен → это domain boundary. Проверить что есть ACL или contract
+
+## Domain boundaries
+- Если сомневаешься, вынеси в отдельный домен
+- Лучше мелкие домены, чем один god-domain
+- README.md: секция "Outside this domain" — обязательна
+
+## When reading domain docs
+- Всегда читай README.md первым — понять границы
+- Потом ubiquitous-language.md — понять термины
+- Потом invariants.md — понять ограничения
+- Только потом остальное

package/template/product-specs/rules/id-numbering.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "product-specs/docs/changes/**"
+  - "product-specs/docs/domains/**"
+---
+
+# ID numbering rules
+
+Stable identifiers (HP-1, EC-3, AC-28, AD-19, AU-15, …) are durable contracts between change packages, domain canon, and code. e2e specs (`apps/web/e2e/hp-{1,2,3}-*.spec.ts`) and runtime handlers (`apps/web/src/domains/identity/widgets/landing/ui/landing-error-toast.tsx`) reference these IDs by name. Reusing or losing one silently breaks tests and traces.
+
+## Counter file
+
+Single source of truth: [`product-specs/docs/changes/_id-counters.json`](../docs/changes/_id-counters.json).
+
+Schema:
+- `counters.<PREFIX>.next` — next free integer for this prefix.
+- `counters.<PREFIX>.stage` / `.owner` — which stage agent is allowed to allocate.
+- `history[]` — per-PRDCT allocation log written by the merger.
+
+## Allocation contract
+
+A stage agent that emits any of these IDs MUST, in the same edit/commit:
+
+1. Read `_id-counters.json`.
+2. For each prefix it will use, take the current `counters.<PREFIX>.next` as the starting number.
+3. Allocate a contiguous block (`next`, `next+1`, …, `next+k-1`).
+4. Write `_id-counters.json` back with `counters.<PREFIX>.next += k` BEFORE finalizing the stage doc.
+
+Prefix → owner:
+
+| Prefix | Stage | Owner |
+|---|---|---|
+| HP, EC, ER, AC, PM, CC, SC | 02-scenarios | studio-scenario-writer |
+| AS, TQ | 03-analysis | studio-analyst |
+| AD | 04-domain | studio-domain-framer |
+| AU, S | 05-ux | studio-designer |
+
+## Format
+
+`<PREFIX>-<NUMBER>`. Padding follows the convention established by PRDCT-0001 (verify against `_id-counters.json` history before the first allocation in a new prefix):
+
+- **Zero-padded to 2 digits always:** `AC` (`AC-01`), `AS` (`AS-01`), `AD` (`AD-01`), `AU` (`AU-01`).
+- **No padding for ≤ 9, 2-digit from 10:** `HP`, `EC`, `ER`, `PM`, `CC`, `SC`, `TQ`, `S` (e.g. `HP-1`, `EC-12`).
+
+## Iron rules
+
+1. **Never reuse a number across PRDCTs.** Even if a prior PRDCT was cancelled or its scenario was deleted — that number is burned.
+2. **Gaps are acceptable.** A cancelled or aborted allocation is wasted, not recycled.
+3. **Anchors required after merge.** When a PRDCT enters `status: done` and `studio-domain-merger` runs, every allocated ID MUST appear as a durable anchor in the affected domain canon — either as a heading (`### HP-1 · …`) or as a bold inline prefix (`**HP-1**: …`). Paraphrasing prose without anchoring is a merge-gate violation.
+
+See [`change-management.md`](./change-management.md) for the wider change-package lifecycle.

package/template/product-specs/rules/obsidian-conventions.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "docs/**"
+---
+
+# Obsidian-specific conventions
+
+## Vault structure
+- Obsidian — основной инструмент для работы с документацией
+- Vault root: `docs/`
+- Canvas файлы (`.canvas`): в `_meta/` для визуальных карт
+- Dataview дашборды: `domains-dashboard.md`, `changes-dashboard.md`
+
+## Graph view optimization
+- Каждый файл ДОЛЖЕН иметь осмысленное имя (НЕ `index.md`)
+- Frontmatter `tags:` используются для группировки и цветов в graph view
+- Рекомендуемые группы в graph:
+  - `path:"domains"` → синий (бизнес-домены)
+  - `path:"changes"` → зелёный (change packages)
+  - `path:"adrs"` → фиолетовый (решения)
+  - `path:"contexts"` → оранжевый (платформа)
+  - `path:"_meta"` → серый (метаданные)
+
+## Canvas files
+- Формат: JSON Canvas (открытый стандарт)
+- Nodes: embed domain README.md через `type: "file"`
+- Edges: подписи = domain events или API contracts
+- Colors: `"4"` = active, `"6"` = planned, `"0"` = infrastructure
+
+## Dataview patterns
+```
+# Таблица из frontmatter:
+TABLE field1, field2 FROM "folder" WHERE type = "X" SORT field1
+
+# Задачи из чеклистов:
+TASK FROM "folder" WHERE file.name = "invariants"
+
+# Группировка:
+TABLE status FROM "changes" WHERE type = "change" GROUP BY status
+```
+
+## Embeds
+- Используй `![[file]]` для встраивания в дашборды
+- Используй `![[file#heading]]` для встраивания секции
+- Canvas: `type: "file"` для embed из vault
+
+## Plugins required
+- **Dataview** — живые дашборды, запросы по frontmatter
+- **Templater** (optional) — динамическое создание файлов из шаблонов
+- **Kanban** (optional) — kanban-доски из markdown
+- **Mermaid** — встроен в Obsidian, доп. плагин не нужен

package/template/product-specs/templates/change/01-intent.md

@@ -0,0 +1,40 @@
+---
+type: change
+status: draft
+tags:
+  - change/PRDCT-XXXX
+  - intent
+created: YYYY-MM-DD
+---
+
+# Intent · PRDCT-XXXX-name
+
+## Problem
+<!-- Какую проблему решаем? Кто страдает? Доказательства (данные, фидбек). -->
+
+## Goal
+<!-- Что хотим получить? Одно предложение. -->
+
+## KPI
+<!-- Как измерим успех? Конкретная метрика + target. -->
+
+## Actors
+| Actor | Role | Key need |
+|-------|------|----------|
+
+## Boundaries
+### In scope
+-
+
+### Out of scope
+-
+
+## Why now
+<!-- Бизнес-причина. Что произойдёт если отложить на 3 месяца? -->
+
+## Risks
+<!-- Продуктовые риски. НЕ технические. -->
+-
+
+## Open questions
+-

package/template/product-specs/templates/change/02-scenarios.md

@@ -0,0 +1,66 @@
+---
+type: change
+status: draft
+tags:
+  - change/PRDCT-XXXX
+  - scenarios
+created: YYYY-MM-DD
+---
+
+# Scenarios · PRDCT-XXXX-name
+
+Контракт поведения системы. Все роли работают от этого документа.
+
+> [!danger] Gate rule
+> Нет scenarios → нельзя писать код. Нельзя писать тесты. Нельзя делать UX.
+
+## Happy path scenarios
+
+### Scenario: [name]
+```gherkin
+Given [precondition]
+When [action]
+Then [result]
+And [side effect]
+```
+
+## Edge case scenarios
+
+### Scenario: [name]
+```gherkin
+Given [unusual precondition]
+When [action]
+Then [expected handling]
+```
+
+## Error scenarios
+
+### Scenario: [name]
+```gherkin
+Given [precondition]
+When [action that fails]
+Then [error handling]
+And [user sees: specific message]
+```
+
+## Permission scenarios
+### Scenario: [role] can/cannot [action]
+```gherkin
+Given user has role [role]
+When user attempts [action]
+Then [allowed/denied with specific response]
+```
+
+## Concurrent scenarios
+### Scenario: [name]
+```gherkin
+Given [two actors doing something simultaneously]
+When [conflict]
+Then [resolution]
+```
+
+## Acceptance criteria
+Derived from scenarios:
+- [ ] AC-01: [from happy path scenario]
+- [ ] AC-02: [from edge case]
+- [ ] AC-03: [from error scenario]

package/template/product-specs/templates/change/03-analysis.md

@@ -0,0 +1,64 @@
+---
+type: change
+status: draft
+tags:
+  - change/PRDCT-XXXX
+  - analysis
+created: YYYY-MM-DD
+---
+
+# System analysis · PRDCT-XXXX-name
+
+> [!info] Принцип
+> Системный анализ определяет ЧТО затронуто и КАКОЙ масштаб изменений. Без конкретных endpoints и schemas — это делает executor.
+
+## Affected systems
+| System / Service | Impact level | What changes |
+|-----------------|-------------|-------------|
+<!-- high / medium / low -->
+
+## Affected bounded contexts
+| Context | Current state | Expected change |
+|---------|-------------|----------------|
+
+## Dependencies
+### Upstream (от кого зависим)
+| System | What we need | Risk if unavailable |
+|--------|-------------|-------------------|
+
+### Downstream (кто зависит от нас)
+| System | What they use | Breaking change? |
+|--------|-------------|-----------------|
+
+## Data impact
+- New data entities needed?
+- Existing data migration required?
+- Data volume expectations:
+- Retention / archival needs:
+
+## Async flows
+<!-- Нужны ли фоновые процессы, очереди, события между сервисами? -->
+```mermaid
+sequenceDiagram
+```
+
+## Integration points
+| Integration | Protocol | Direction | New / Changed / Existing |
+|------------|----------|-----------|------------------------|
+
+## Technical risks
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|-----------|
+
+## Constraints
+<!-- Технические ограничения, которые влияют на решение -->
+- Performance:
+- Scalability:
+- Security:
+- Compliance:
+
+## Open technical questions
+-
+
+> [!danger] Gate rule
+> Нет analysis → нельзя моделировать домен. Без понимания масштаба impact нельзя определять boundaries.

package/template/product-specs/templates/change/04-domain.md

@@ -0,0 +1,47 @@
+---
+type: change
+status: draft
+tags:
+  - change/PRDCT-XXXX
+  - domain
+created: YYYY-MM-DD
+---
+
+# Domain framing · PRDCT-XXXX-name
+
+## Affected bounded contexts
+| Context | Impact | What changes |
+|---------|--------|-------------|
+
+## Aggregate changes
+
+### [Aggregate name]
+**Responsibility:**
+**New/changed fields:**
+**State machine changes:**
+
+```mermaid
+stateDiagram-v2
+```
+
+## New/changed business rules
+| Rule | Description | Rationale | Edge cases |
+|------|------------|-----------|------------|
+
+## New/changed events
+| Event | Producer | Consumers | Payload | Guarantees |
+|-------|----------|-----------|---------|-----------|
+
+## Invariants check
+<!-- Для каждого инварианта затронутого домена -->
+- [ ] [invariant] · ✅ preserved / ⚠️ impacted / ❌ violated
+
+## New invariants
+-
+
+## Ubiquitous language
+| Term | Definition | Forbidden synonyms |
+|------|-----------|-------------------|
+
+> [!danger] Gate rule
+> Нет domain framing → нельзя делать UX. Нельзя делать код.

package/template/product-specs/templates/change/05-ux.md

@@ -0,0 +1,46 @@
+---
+type: change
+status: draft
+tags:
+  - change/PRDCT-XXXX
+  - ux
+created: YYYY-MM-DD
+---
+
+# UX projection · PRDCT-XXXX-name
+
+> [!info] Принцип
+> UI не придумывает логику — он показывает её. Каждый экран = отражение сценария.
+
+## Surfaces
+| Surface | Type | Scenario ref | Mockup |
+|---------|------|-------------|--------|
+
+## Flows
+
+### [Flow name] (ref: scenario [name])
+1. [step] → screen [X]
+2. [step] → screen [Y]
+
+## States per surface
+
+### [Surface name]
+| State | Description | Mockup | data-test-id |
+|-------|------------|--------|-------------|
+| loading | | [[mockups/state-X-loading.html]] | state-X-loading |
+| success | | [[mockups/state-X-success.html]] | state-X-success |
+| error | | [[mockups/state-X-error.html]] | state-X-error |
+| empty | | [[mockups/state-X-empty.html]] | state-X-empty |
+
+## Error messages
+| Error | User message | Recovery action | data-test-id |
+|-------|-------------|----------------|-------------|
+
+## Transitions
+```mermaid
+stateDiagram-v2
+```
+
+## Mockups
+All HTML mockups in `mockups/` directory:
+- [[mockups/flow-X.html]]

package/template/product-specs/templates/change/metadata.yaml

@@ -0,0 +1,26 @@
+id: PRDCT-XXXX-name
+title: ""
+status: intent
+# status: intent | scenarios | analysis | domain | ux | done
+
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+
+owners:
+  product: ""
+  backend: ""  # also architect
+  designer: ""
+  frontend: ""
+  qa: ""
+
+domains: []
+capabilities: []
+
+related_changes: []
+pr_links: []
+
+blocked_by: ""
+conflicts_with: []
+
+retroactive: false
+retroactive_note: ""

package/template/product-specs/templates/config.json

@@ -0,0 +1,19 @@
+{
+  "version": "0.1.0",
+  "role": "fullstack",
+  "model_profile": "balanced",
+  "handoff_mode": "branch",
+  "autonomous_allowed": false,
+  "obsidian_integration": true,
+  "language": "ru",
+  "stage_pipeline": ["draft", "discovery", "spec", "analysis", "design", "in-progress", "done"],
+  "roles": {
+    "pm": { "commands": ["pm", "feature", "status", "sync"] },
+    "analyst": { "commands": ["analyst", "new-domain", "status", "review"] },
+    "designer": { "commands": ["designer", "status"] },
+    "backend": { "commands": ["backend", "bug", "status", "verify"] },
+    "frontend": { "commands": ["frontend", "bug", "status", "verify"] },
+    "qa": { "commands": ["qa", "review", "status", "verify"] },
+    "fullstack": { "commands": ["*"] }
+  }
+}

package/template/product-specs/templates/domain/README.md

@@ -0,0 +1,31 @@
+---
+type: domain
+domain: DOMAIN_NAME
+status: draft
+owner: ""
+tags:
+  - domain
+created: YYYY-MM-DD
+---
+
+# [Domain name]
+
+## What is this domain
+<!-- Один абзац: какую бизнес-возможность представляет этот домен -->
+
+## Why it exists
+<!-- Бизнес-обоснование -->
+
+## Boundaries
+
+### Inside this domain
+-
+
+### Outside this domain (explicitly)
+-
+
+## Key use cases
+-
+
+## Owned by
+<!-- Команда или ответственный -->

package/template/product-specs/templates/domain/aggregates.md

@@ -0,0 +1,37 @@
+---
+type: aggregate
+domain: DOMAIN_NAME
+tags:
+  - domain/DOMAIN_NAME
+  - aggregate
+---
+
+# Aggregates · [Domain name]
+
+## [Aggregate name]
+
+### Responsibility
+
+### State diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> State1
+    State1 --> State2: action()
+    State2 --> [*]
+```
+
+### Structure
+
+```mermaid
+erDiagram
+    AGGREGATE {
+        uuid id PK
+    }
+```
+
+### Boundaries
+
+### Consistency rules
+
+### Cannot be split from

package/template/product-specs/templates/domain/api-contracts.md

@@ -0,0 +1,29 @@
+---
+type: api-contracts
+domain: _template
+status: draft
+tags:
+  - domain/_template
+  - api
+created: YYYY-MM-DD
+---
+
+# API contracts
+
+## Owned endpoints
+| Method | Path | Description | Auth | Request | Response |
+|--------|------|-------------|------|---------|----------|
+
+## Consumed endpoints (from other domains)
+| Method | Path | Provider domain | Purpose |
+|--------|------|----------------|---------|
+
+## Error codes
+| Code | Meaning | When |
+|------|---------|------|
+
+## Versioning
+<!-- Стратегия версионирования API этого домена -->
+
+## OpenAPI specs
+<!-- Ссылки на актуальные openapi.yaml из change packages -->