gennady 0.6.0 → 0.7.0

package/dist/ai/directives/sdd/setup.directive.xml

@@ -0,0 +1,213 @@
+<SddSetup keywords="setup, project-init, portal, scope-graph, vision, infra-bootstrap, idempotent, sdd-project-setup" type="directive" ver="1.1">
+  <Directive_Context>
+    <Mission>
+      Primary owner of `specs/README.md` — Project Vision and Scope Graph. Idempotent: runs any number of times to refine vision, extend the scope graph, or bootstrap the first infra-base spec.
+
+      Input — operator intent (what we create / what we change at project level).
+      Output:
+      - `specs/README.md` with Vision + Scope Graph + Scopes table.
+      - Optional: a minimal `specs/infra-base/infra-base.spec.md` (first infra-scope bootstrap) if the operator declared tooling.
+
+      Out of scope: details of any individual scope (its vision, architecture, requirements, modules) — that is the job of `discovery`. `setup` writes only the project-level map.
+
+      **Glossary.** scope-type ∈ {infrastructure, contracts, library, product}. Scope Graph = directed graph; edge A→B = «scope A depends on scope B (consumes its rules / contracts)».
+    </Mission>
+  </Directive_Context>
+
+  <Belief_State>
+    <Axiom id="AX_PORTAL_PRIMARY_OWNER">
+      `setup` is the primary owner of `specs/README.md`. Other directives MUST NOT rewrite this file. Reads are unrestricted.
+
+      Explicit, narrow exceptions (append-only edits permitted, no rewrites):
+      - `discovery` creating a brand-new scope MAY append a placeholder row to the Scopes table tagged `🚧 (awaiting setup sync)` so the new scope is visible in the Portal before the next `setup` run.
+      - `module-decomposition` MUST NOT touch this file; its Portal-level summaries are appended only to its scope spec.
+
+      Any other edit by another directive → audit finding `STALE_AFTER_PIVOT` or `EXECUTION_LOG_INCOMPLETE` depending on context. The next `setup` run reconciles placeholders into full rows.
+    </Axiom>
+
+    <Axiom id="AX_IDEMPOTENT_MODES">
+      `setup` has no hard modes (no greenfield / extension / pivot).
+      - Portal absent → create from scratch.
+      - Portal present → read and propose updates derived from intake; operator dictates what to change.
+
+      No silent assumptions: empty intake against an existing Portal → HALT `H_NO_INTENT` («what are we changing today?»).
+    </Axiom>
+
+    <Axiom id="AX_SCOPE_GRAPH_DISCIPLINE">
+      Scope Graph is a directed dependency graph. Rules:
+      - Edge A→B means «scope A depends-on scope B»: A inherits B's effective rules in the cascade and may consume B's contracts.
+      - Cycle in the graph → `H_CYCLE_IN_GRAPH` (abort).
+      - scope-type constraints: `infrastructure` and `contracts` scopes are typically leaves (depend only on other infra / contracts). `product` and `library` scopes depend on infra + contracts.
+      - The graph is rendered as a Mermaid `graph TD` block inside the Portal.
+    </Axiom>
+
+    <Axiom id="AX_INFRA_BASE_BOOTSTRAP">
+      If the operator declares basic tooling (package manager, type-checker, linter) in intake, `setup` materializes a minimal `specs/infra-base/infra-base.spec.md` with scope-type=infrastructure: Vision (one sentence) + Tool Stack (table with tool names only, no Decision Log yet). The full Decision Log appears when the operator runs `discovery infra-base`.
+
+      The minimal bootstrap intentionally bypasses the full `discovery` flow — it only locks the tool choice without the Design Variants ritual.
+    </Axiom>
+
+    <Axiom id="AX_SCOPE_TABLE_FORMAT">
+      Scopes table in the Portal: each row = link to the scope spec + scope-type + status emoji + one-line description.
+      - ✅ — spec exists and is approved.
+      - 🚧 — spec being authored / `discovery` not yet run.
+      - Status is derived purely from the presence of `specs/<scope>/<scope>.spec.md`.
+    </Axiom>
+
+    <Axiom id="AX_VISION_ONLY_FOR_APPLICATION">
+      The `## Vision` section in the Portal is present only when the project contains at least one product or library scope. For tooling-only repos (sandboxes, infra repos) the Vision section is omitted.
+    </Axiom>
+
+    <Axiom id="AX_DIALOGUE_DISCIPLINE">
+      - Neutrality: no auto-agree. Every proposed scope must pass the «scope vs module» test.
+      - If the operator labels as «scope» something that is obviously a module inside an existing scope, surface this and propose adding it as a module via `module-decomposition`.
+      - Phase agreement: agent signals `STATUS=READY_TO_ADVANCE`; operator confirms.
+    </Axiom>
+
+    <Axiom id="AX_OPERATOR_LANGUAGE">
+      **Directive prose (axioms, halt names, step procedures, contract identifiers, structural section headings) — English.**
+      **Operator-facing artifact prose and operator-facing messages — Russian.** Russian applies to:
+      - Portal body text inside `specs/README.md` (Vision, Scope descriptions in the table, Notes).
+      - Minimal infra-base spec body (Vision sentence, table cell content beyond identifiers).
+      - Halt messages emitted to the operator.
+      - Phase Progress free-text fields.
+
+      English regardless of context: file paths, axiom IDs (`AX_*`), Trace anchors (`SU_R<N>`), status tokens, scope-type tokens, section identifiers (`Vision`), Mermaid graph IDs.
+    </Axiom>
+
+    <Axiom id="AX_STATELESS_ARTIFACT">
+      `specs/README.md` is self-contained. The next session reads only that file, without conversation history.
+    </Axiom>
+  </Belief_State>
+
+  <Halt_Conditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_NO_INTENT` | Operator invoked `setup` with an empty intake against an existing Portal |
+    | `H_CYCLE_IN_GRAPH` | Scope Graph contains a cycle |
+    | `H_SCOPE_VS_MODULE_AMBIGUITY` | Operator labels as «scope» something that resembles a module — clarification required |
+    | `H_OPERATOR_REJECT` | Operator rejected Vision, Scope Graph, or the final Portal |
+  </Halt_Conditions>
+
+  <Execution_Plan>
+    <Step id="STEP_0_INTAKE">
+      <Goal>Inspect Portal; determine today's change set.</Goal>
+      <Action>
+        1. Stat `specs/README.md`:
+           - Absent → init mode (build from scratch). Ask the operator: «Как называется проект? Опиши в одном предложении его vision и первые scope'ы (infra-base, backend, web — на черновую).»
+           - Present → read in full. Empty intake → `H_NO_INTENT`. Otherwise classify the change: vision / add scope / update graph / infra bootstrap.
+        2. Proceed to STEP_1.
+      </Action>
+    </Step>
+
+    <Step id="STEP_1_VISION">
+      <Goal>Lock the project-level Vision.</Goal>
+      <Action>
+        1. If the project has no product / library scopes → skip Vision (per `AX_VISION_ONLY_FOR_APPLICATION`).
+        2. Propose Vision (one sentence): what we build and which problem it solves.
+        3. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_2_SCOPE_GRAPH">
+      <Goal>Capture scopes and their dependency edges.</Goal>
+      <Action>
+        1. For each scope from the operator:
+           a. Propose scope-type with rationale.
+           b. Run the «scope vs module» test; surface mismatches.
+           c. Naming convention: `infra-*` / `design-system-*` / `api-contracts` / plain.
+        2. Capture `depends-on` edges.
+        3. Cycle check → `H_CYCLE_IN_GRAPH`.
+        4. Render the Mermaid graph.
+        5. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_3_INFRA_BOOTSTRAP">
+      <Goal>If the operator declared tooling — materialize the minimal infra-base spec.</Goal>
+      <Action>
+        1. No tooling declared → skip.
+        2. Create `specs/infra-base/infra-base.spec.md` with:
+           - scope-type: infrastructure
+           - Vision: one sentence about dev experience.
+           - Tool Stack: table of tools (no Decision Log yet).
+           - Note: «Полный Decision Log — запусти `discovery infra-base`».
+        3. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_4_PORTAL_WRITE">
+      <Goal>Write / update `specs/README.md`.</Goal>
+      <Action>
+        1. Assemble Portal per `PORTAL_STRUCTURE_CONTRACT`.
+        2. For each scope: stat `specs/<scope>/<scope>.spec.md` → status ✅ or 🚧.
+        3. Reconcile any placeholder rows left by `discovery` (per `AX_PORTAL_PRIMARY_OWNER`) into full rows.
+        4. Write the file.
+        5. Approval Check. STOP.
+      </Action>
+    </Step>
+  </Execution_Plan>
+
+  <Output_Contracts>
+    <Contract id="TRACE_HEADER_FORMAT">
+      ```text
+      🗺️ SU_R<N> | STACK: ROOT__<STEP> | <STATUS> | CONF: <LOW|MEDIUM|HIGH>
+      🎯 GOAL: <local goal>
+      ⏭️ EXIT: <exit condition>
+      ```
+    </Contract>
+
+    <Contract id="PORTAL_STRUCTURE_CONTRACT">
+      ```markdown
+      # <project-name>
+
+      ## Vision
+      <Одно предложение. Опускается для infrastructure-only проектов.>
+
+      ## Scope Graph
+
+      ```mermaid
+      graph TD
+        backend --> infra-base
+        backend --> api-contracts
+        web --> infra-base
+        web --> api-contracts
+        web --> design-system-core
+        mobile --> api-contracts
+      ```
+
+      ## Scopes
+
+      | Scope | Type | Spec | Description |
+      |---|---|---|---|
+      | [`infra-base`](./infra-base/infra-base.spec.md) | infrastructure | ✅ | TS + pnpm + vitest + biome |
+      | [`api-contracts`](./api-contracts/api-contracts.spec.md) | contracts | 🚧 | REST API v1 |
+      | [`backend`](./backend/backend.spec.md) | product | ✅ | Node.js IMAP-сервис |
+      | [`web`](./web/web.spec.md) | product | 🚧 | React SPA |
+      ```
+    </Contract>
+
+    <Contract id="INFRA_BASE_MINIMAL_SPEC">
+      ```markdown
+      # <scope-name>: Infrastructure Specification
+
+      ## scope-type
+      infrastructure
+
+      ## 1. Vision
+      <Одно предложение про dev-experience.>
+
+      ## 2. Tool Stack (minimal bootstrap)
+      | Category | Tool |
+      |---|---|
+      | package-management | <tool> |
+      | type-check | <tool> |
+      | linting+formatting | <tool> |
+      | test-unit | <tool> |
+      | git-hooks | <tool> |
+
+      > Полный Decision Log (Design Variants, rationale, Effective Rules для cascade) — запусти `discovery <scope-name>`.
+      ```
+    </Contract>
+  </Output_Contracts>
+</SddSetup>

package/dist/ai/directives/sdd/svelte-ui-discovery.directive.xml

@@ -0,0 +1,263 @@
+<SvelteUiDiscovery keywords="svelte, ui-component, figma, svg, design-tokens, vkui, paradigm, storybook, sdd, component-discovery" type="directive" ver="1.0">
+  <Directive_Context>
+    <Mission>
+      Провести оператора через создание SDD-спеки Svelte UI-компонента: от Figma SVG-макета до утверждённого `.ui.spec.md`, готового к scaffold.
+      
+      Вход: имя компонента + SVG-макет в `specs/<scope>/_figma/<name>.svg`.
+      Выход: `specs/<scope>/components/<name>.ui.spec.md` — самодостаточная спека компонента по секциям SPEC_STRUCTURE.
+      
+      Не scope-level, не module-level — компонент-level. Директива дополняет основной SDD flow: используется при запуске discovery для UI-компонента внутри любого scope (uikit, app, etc.).
+      
+      Процесс многоступенчатый: на каждом шаге агент извлекает данные из SVG через figma-utils, показывает вывод оператору, оператор подтверждает или поправляет. Без подтверждения — не идём дальше.
+      
+      Как активируется: оператор запускает SDD-сессию с указанием этой директивы — «создать компонент Button по svelte-ui-discovery».
+    </Mission>
+  </Directive_Context>
+
+  <Belief_State>
+    <Axiom id="AX_TOOLS_AS_HANDS">
+      figma-utils — руки агента в SVG, не источник истины. Агент использует команды для извлечения контекста, но решения принимает сам:
+      
+      - `figma:extract <name>` — полный JSON со всеми вариантами, измерениями, токен-кандидатами
+      - `figma:inspect <name> <pattern>` — точечный зум в конкретный вариант: размеры, элементы, fill/stroke
+      - `figma:tokens find <pattern>` — grep по именам токенов дизайн-системы
+      - `figma:tokens near <value> [delta]` — найти токены, близкие к измеренному значению
+      - `figma:tokens groups` — категории токенов
+      
+      Агент НЕ должен полагаться только на extract. Если данные неполны или противоречивы — запустить inspect для конкретных вариантов, найти токены near, перепроверить.
+    </Axiom>
+
+    <Axiom id="AX_STEP_BY_STEP_APPROVAL">
+      Многоступенчатый flow. Каждый шаг завершается Approval Check — оператор подтверждает или поправляет. Без подтверждения следующий шаг не начинается.
+      
+      Шаги:
+      1. SKELETON — скелет компонента (иерархия, слоты)
+      2. AXES — оси вариативности (size, appearance, mode, state)
+      3. TOKENS — дизайн-токены (маппинг, overrides)
+      4. API — пропсы, события, слоты
+      5. A11Y — доступность
+      6. STORYBOOK — план stories
+      7. FINAL — утверждение спеки
+    </Axiom>
+
+    <Axiom id="AX_EXISTING_COMPONENTS_CHECK">
+      Перед созданием нового компонента — проверить существующие. Шаг 0:
+      - Есть ли в `specs/<scope>/components/` спека с похожим именем?
+      - Можно ли собрать нужный вариант из existing компонента (композиция)?
+      - Можно ли доработать existing (добавить mode/appearance/size)?
+      
+      Если existing подходит — не создаём новый, а запускаем refine existing. Результат фиксируется в Decision Log.
+    </Axiom>
+
+    <Axiom id="AX_SVELTE_CONVENTIONS">
+      Компонент — Svelte 5 с runes. Конвенции из `infra-ui`:
+      - data-атрибуты: `.btn[data-mode="primary"]`, не `:host()`
+      - CSS custom properties: `var(--vkui--...)` через `:root`
+      - Файлы: `<name>.svelte` + `<name>.module.css` + `<name>.tokens.css` + `<name>.stories.ts`
+      - Именование: kebab-case, lower-case
+      - `data-state` для тестируемости hover/active/disabled
+      - Counter: `box-sizing: border-box`
+    </Axiom>
+
+    <Axiom id="AX_TOKEN_DISCIPLINE">
+      Токены — семантический маппинг, не числовой:
+      - Маппинг по имени токена (height → `--vkui--size_button_small_height--compact`)
+      - diff ≤ 1px → OK (субпиксельный рендеринг)
+      - diff > 1px → OVERRIDE с комментарием `/* override: was Xpx */`
+      - Токен не найден → новый компонентный токен `--paradigm--<component>-*`
+      - Цвета — через VKUI-токены, не хардкод
+    </Axiom>
+
+    <Axiom id="AX_EVIDENCE_HYGIENE">
+      Факты / Предположения / Гипотезы — разделены в каждом intake-фрейме.
+      - Факты — из figma:extract (измерения, цвета, классификация)
+      - Предположения — семантическая интерпретация (этот элемент — иконка, этот — счётчик)
+      - Гипотезы — требуют валидации оператором (disabled определяется по opacity группы)
+    </Axiom>
+
+    <Axiom id="AX_SPEC_STRUCTURE">
+      Формат `.ui.spec.md` — секции SPEC_STRUCTURE:
+      1. Vision &amp; Purpose — назначение компонента
+      2. Anatomy — ASCII-дерево слотов + таблица (имя, назначение, обязательность)
+      3. Variant Axes — оси вариативности (size, appearance, mode, state) с таблицами значений
+      4. States — состояния (default, hover, active, disabled, loading) с поведением
+      5. Design Tokens — таблица токенов (роль → VKUI-токен → значение → override)
+      6. API — пропсы (имя, тип, по умолчанию, описание)
+      7. Accessibility — role, aria, keyboard
+      8. Storybook Plan — иерархия stories, количество вариантов
+      9. BDD Scenarios — по одному на состояние × appearance × mode
+    </Axiom>
+
+    <Axiom id="AX_OPERATOR_LANGUAGE">
+      Директивная проза — English. Артефакты и сообщения оператору — Russian.
+    </Axiom>
+  </Belief_State>
+
+  <Execution_Plan>
+    <Step id="STEP_0_EXISTING_CHECK">
+      <Goal>Проверить существующие компоненты. Можно ли переиспользовать?</Goal>
+      <Action>
+        1. Прочитать `specs/<scope>/components/` — список существующих спек.
+        2. Если есть компонент с похожим именем — предложить refine вместо create.
+        3. Если можно скомпоновать из existing — предложить композицию.
+        4. Результат → Decision Log.
+        5. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_1_SKELETON">
+      <Goal>Понять анатомию компонента из SVG.</Goal>
+      <Action>
+        1. `figma:extract <name>` — получить все варианты.
+        2. `figma:inspect <name> <first-variant>` — посмотреть конкретный вариант.
+        3. Предложить ASCII-дерево слотов (icon, label, counter, indicator).
+        4. Таблица: слот, назначение, обязательность.
+        5. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_2_AXES">
+      <Goal>Определить оси вариативности.</Goal>
+      <Action>
+        1. Из extract: уникальные size, appearance, mode, state.
+        2. Предложить таблицы значений для каждой оси.
+        3. Указать невалидные комбинации (если есть).
+        4. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_3_TOKENS">
+      <Goal>Смаппить измерения на дизайн-токены.</Goal>
+      <Action>
+        1. Из extract: tokenOverrides для каждого измерения.
+        2. `figma:tokens near <value>` — найти токены по значению.
+        3. `figma:tokens find <pattern>` — найти токены по имени.
+        4. Предложить таблицу: роль → VKUI-токен → значение SVG → значение токена → diff → решение (OK/OVERRIDE/NEW).
+        5. Для отсутствующих токенов — предложить `--paradigm--<component>-*`.
+        6. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_4_API">
+      <Goal>Спроектировать API компонента.</Goal>
+      <Action>
+        1. Пропсы: из осей (appearance, mode, size, state) + контентные (before/after, label, counter) + поведенческие (disabled, loading, stretched).
+        2. Типы, значения по умолчанию.
+        3. События: click, нет специфичных.
+        4. Слоты: соответствие анатомии.
+        5. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_5_A11Y">
+      <Goal>Определить требования доступности.</Goal>
+      <Action>
+        1. Role: button.
+        2. aria-label, aria-disabled, aria-busy.
+        3. Keyboard: Enter, Space.
+        4. Focus: outline.
+        5. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_6_STORYBOOK">
+      <Goal>Спланировать Storybook-истории.</Goal>
+      <Action>
+        1. Иерархия: Component / Appearance / Mode / Size × State.
+        2. Количество stories: уникальные комбинации из осей.
+        3. Play-функции: render + interaction + expect.
+        4. A11y-аудит: parameters.
+        5. Approval Check. STOP.
+      </Action>
+    </Step>
+
+    <Step id="STEP_7_FINAL">
+      <Goal>Сгенерировать и утвердить `.ui.spec.md`.</Goal>
+      <Action>
+        1. Собрать все секции по SPEC_STRUCTURE.
+        2. Записать `specs/<scope>/components/<name>.ui.spec.md`.
+        3. Decision Log: D-001 (decomposition axis), D-002 (token overrides).
+        4. Handoff: готово к scaffold.
+        5. Approval Check. STOP.
+      </Action>
+    </Step>
+  </Execution_Plan>
+
+  <Halt_Conditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_NO_SVG` | SVG-макет не найден в `_figma/` |
+    | `H_EXTRACT_FAILED` | `figma:extract` упал — починить инструменты перед продолжением |
+    | `H_OPERATOR_REJECT` | Оператор отверг предложение на любом шаге |
+    | `H_EXISTING_BETTER` | Существующий компонент покрывает потребность — refine вместо create |
+  </Halt_Conditions>
+
+  <Output_Contracts>
+    <Contract id="SPEC_STRUCTURE">
+      ```markdown
+      # <ComponentName> — спецификация компонента
+
+      ## 1. Vision & Purpose
+      [Назначение, контекст использования, отличия от похожих компонентов.]
+
+      ## 2. Anatomy
+      [ASCII-дерево слотов.]
+      
+      | Слот | Назначение | Обязательность |
+      |---|---|---|
+      | `<name>` | `<purpose>` | yes / no |
+      
+      [Нюансы реализации.]
+
+      ## 3. Variant Axes
+      ### `size` — размер
+      | Значение | Высота | Padding X | Gap | Описание |
+      |---|---|---|---|---|
+      
+      ### `appearance` — цветовая тема
+      ### `mode` — степень акцента
+      
+      [Невалидные комбинации, если есть.]
+
+      ## 4. States
+      | Состояние | Поведение |
+      |---|---|
+      | default | ... |
+      | hover | ... |
+      | active | ... |
+      | disabled | ... |
+      | loading | ... |
+
+      ## 5. Design Tokens
+      | Роль | VKUI-токен | Значение SVG | Значение токена | Diff | Решение |
+      |---|---|---|---|---|---|
+      
+      [Override-токены с комментариями.]
+      [Новые токены: `--paradigm--<component>-*`.]
+
+      ## 6. API
+      | Проп | Тип | По умолчанию | Описание |
+      |---|---|---|---|
+
+      ## 7. Accessibility
+      - Role: button
+      - aria-label: ...
+      - Keyboard: Enter, Space
+
+      ## 8. Storybook Plan
+      [Иерархия: Component / Appearance / Mode / Size × State.]
+      [Количество stories.]
+
+      ## 9. BDD Scenarios
+      ### <appearance> / <mode> / <state>
+      - **Given** ...
+      - **When** ...
+      - **Then** ...
+
+      ## 10. Decision Log
+      ### D-001 — ...
+      ## 11. Handoff
+      ```
+    </Contract>
+  </Output_Contracts>
+</SvelteUiDiscovery>

package/dist/ai/directives/semantic-change-extractor.directive.xml

@@ -0,0 +1,99 @@
+<Semantic_Change_Extractor keywords="git, semantic diff, code analysis, reverse engineering, intent extraction, merge conflict resolution, semantic rebase" type="directive" ver="2.0">
+  <Mission>
+    Analyze git branch changes from the branching point to current HEAD, extract semantic intent, map cross-file dependencies, and emit a portable, intent-based XML/Markdown artifact for another agent to implement.
+
+    Reverse-engineering, not syntactic diff: abstract away from raw lines; focus on business logic, data flow, cross-file dependencies, developer's underlying intent.
+  </Mission>
+
+  <Belief_State>
+    <Axiom id="AX_INTENT_OVER_LINES">Raw git diffs (line/column numbers) are fragile and useless for transferring changes to heavily modified branches. Extract the *intent* and *semantic location* (e.g., «inside the user authentication loop», «before the database commit»), not raw lines.</Axiom>
+    <Axiom id="AX_CONTEXT_IS_KING">Change without a consumer is a bug. Always identify *why* a change was made and *who/what* consumes it (e.g., «Frontend expects a new JSON field», «Fixes a memory leak in the worker»).</Axiom>
+    <Axiom id="AX_GROUPING_REDUCES_NOISE">Multiple scattered changes in a file with one shared intent (mass renaming, parameter added to many calls) MUST be grouped into a single logical task. Per-line entries are noise.</Axiom>
+    <Axiom id="AX_CROSS_FILE_COHESION">Changes rarely happen in isolation. Service signature change → controller calling it must change. Map dependencies explicitly via `<depends_on>` so the implementing agent applies them in correct order.</Axiom>
+    <Axiom id="AX_AUTONOMOUS_DISCOVERY">Fetch own context. Target branch unknown → auto-detect default branch (`git symbolic-ref refs/remotes/origin/HEAD` or branch analysis) to find the correct merge base.</Axiom>
+  </Belief_State>
+
+  <Execution_Plan>
+    1. Auto-detect main/target branch via bash if not provided.
+    2. Find merge base: `git merge-base <target> HEAD`.
+    3. List changed files: `git diff --name-only <merge-base> HEAD`.
+    4. For each file, extract diff AND read full file content (`cat <file>`) for surrounding context — not only diff chunks.
+    5. Emit `<Context_Analysis>` mapping intents, groupings, cross-file dependencies.
+    6. Emit `<Branch_Changes>` artifact.
+  </Execution_Plan>
+
+  <Output_Format>
+    Two phases.
+    - **Phase 1**: `<Context_Analysis>` — English or Russian.
+    - **Phase 2**: `<Branch_Changes>` — content inside the artifact tags MUST be in RUSSIAN; use Markdown directly inside the tags. File-tag name = sanitized path (slashes/dots → underscores).
+
+    ```xml
+    <Context_Analysis>
+      1. Target Branch & Merge Base Identification.
+      2. High-level summary of what this branch achieves (the «Epic»).
+      3. File → logical intent mapping (grouping strategy).
+      4. Cross-file dependencies (e.g., «UserService change dictates UserController change»).
+    </Context_Analysis>
+
+    <Branch_Changes source="[current_branch_name]" base="[merge_base_hash]">
+      <src_services_UserService_ts>
+        <changes id="add_role_validation">
+          <purpose>Добавить проверку ролей при создании пользователя.</purpose>
+          <consumer>API Gateway, Middleware авторизации.</consumer>
+          <location file="src/services/UserService.ts">Внутри метода `createUser`, после валидации email, перед сохранением в БД. В блоке импортов добавить `RoleValidator`.</location>
+          <description>
+            **General:** Интегрировать `RoleValidator.check(user.role)` в процесс создания.
+
+            **Insights:** Если валидатор кидает ошибку — обернуть в `CustomAuthError` для корректного HTTP 403.
+
+            **Snippet:**
+            ```typescript
+            if (!RoleValidator.check(payload.role)) {
+                throw new CustomAuthError("Invalid role assignment");
+            }
+            ```
+          </description>
+        </changes>
+      </src_services_UserService_ts>
+
+      <src_controllers_UserController_ts>
+        <changes id="pass_role_to_service">
+          <purpose>Передать `role` из тела запроса в сервис создания.</purpose>
+          <consumer>`UserService.createUser`.</consumer>
+          <depends_on>add_role_validation</depends_on>
+          <location file="src/controllers/UserController.ts">Внутри обработчика POST `registerUser`, при формировании `payload` для сервиса.</location>
+          <description>Извлечь `req.body.role`, добавить в payload. Default `"user"` если не передан.</description>
+        </changes>
+      </src_controllers_UserController_ts>
+
+      <src_utils_oldLogger_js>
+        <changes id="remove_legacy_logger">
+          <purpose>Удалить устаревший логгер; проект полностью на Winston.</purpose>
+          <consumer>Система логирования.</consumer>
+          <location file="src/utils/oldLogger.js">Весь файл.</location>
+          <description>Файл удалить полностью. Вычистить импорты `oldLogger.js` в целевой ветке.</description>
+        </changes>
+      </src_utils_oldLogger_js>
+    </Branch_Changes>
+    ```
+  </Output_Format>
+
+  <Invariants>
+    - Semantic anchor for `<location>` («in the class constructor»), never absolute line numbers.
+    - Logically connected changes grouped into single `<changes>` block.
+    - Cross-file dependencies linked via `<depends_on>`.
+    - Markdown inside XML tags is direct (no CDATA, no over-escaping).
+    - `<Context_Analysis>` MUST precede `<Branch_Changes>` emission (Phase 1 before Phase 2).
+    - File-tag name is unique sanitized path (slashes/dots → underscores).
+    - Forbidden: copy-pasting raw `git diff` output with `+`/`-` signs; absolute line numbers as primary locator.
+  </Invariants>
+
+  <Self_Check>
+    Before emitting `<Branch_Changes>`:
+    1. Did `<Context_Analysis>` map intents, groupings, cross-file dependencies?
+    2. Are file-tag names unique and derived from sanitized paths?
+    3. Is every `<location>` semantic (immune to line drift)?
+    4. Is every multi-file change linked via `<depends_on>` where applicable?
+    5. Are scattered same-intent changes grouped into one `<changes>` block?
+  </Self_Check>
+</Semantic_Change_Extractor>

package/dist/ai/directives/testing/README.md

@@ -0,0 +1,25 @@
+# Testing rules
+
+Test framework usage policy: structure, fixtures, isolation, naming.
+
+## Currently available
+
+- [`common.xml`](common.xml) — **Shared testing core** inherited by every runner-specific directive. Contract boundary, case flow, phase anchors, unified context + factory, BDD mapping, snapshot operator-confirm, file budget. Read first.
+- [`node-test.xml`](node-test.xml) — Node.js built-in `node:test` runner specifics on top of `common`: assert API, native `mock.fn()`, HTTP mock-agent, snapshot file location.
+- [`vitest-rules.xml`](vitest-rules.xml) — Vitest runner specifics on top of `common`: `vitest run` (not watch), `vi`-matcher API, `vi.mock` confirm-gate, mock hygiene, time/env lifecycle, explicit imports.
+- [`playwright-cli.xml`](playwright-cli.xml) — Playwright CLI exploration & debugging: AX Tree vision, aria snapshots, trace viewer, codegen, headless self-verification. **Prerequisite for playwright-e2e.**
+- [`playwright-e2e.xml`](playwright-e2e.xml) — Playwright e2e test authoring: aria-snapshot-first contracts, role-based locators, fixture-based POM, auth via storageState, network mocking. **Activated after CLI exploration.**
+- [`storybook-usage.xml`](storybook-usage.xml) — Storybook MCP tools for component development: reading manifests (component docs, props, stories), writing stories, running tests, self-verifying component rendering. **Activated when MCP server is running.**
+- [`svelte-testing.xml`](svelte-testing.xml) — Testing Svelte 5 components: `.svelte.test.ts` extension, `$effect.root`, `flushSync`, `mount`/`unmount`, `@testing-library/svelte`. **Inherits node-test + vitest-rules.**
+
+## Planned
+
+- `jest.xml` — Jest usage (legacy projects).
+- `cypress.xml` — alternative E2E runner.
+- `storybook.xml` — UI component testing in isolation.
+- `pytest.xml` — Python testing: fixtures, parametrization, conftest patterns.
+- `go-test.xml` — Go testing: table-driven tests, subtests, golden files.
+
+## Activation default
+
+Testing rules activate `later` by default per `AX_RULE_ACTIVATION_DEFAULTS` — they're consumed by execution agents when test files are written, not walked through with the operator at selection time. Override to `now` if a test rule has strong opinions worth surfacing (e.g., snapshot-discipline policy for a UI library).