gennady 0.8.3 → 0.8.4-draft.2

package/ai/kit/axiom/truth/ax-reuse-first.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/sdd/critic.directive.xml -->
+<Axiom id="AX_REUSE_FIRST">Orchestrator holds full project context — the ONLY actor able to detect duplication against existing code/specs (the isolated critic cannot). For every entity/type/method/contract the artifact introduces, reconcile before accepting it: REUSE existing (adapt artifact to it) > EXTEND existing > JUSTIFY new (record one-line rationale in artifact: why existing surface is insufficient) > ESCALATE to operator. Unjustified new surface is a finding to resolve, not to wave through. Bias toward consolidation — do not let the system grow a duplicate entity each round.</Axiom>

package/ai/kit/axiom/truth/ax-spec-is-sole-source.xml

@@ -0,0 +1,6 @@
+<!-- source: sdd/discovery + scaffold + module-decomposition (converged to principle) -->
+<Axiom id="AX_SPEC_IS_SOLE_SOURCE">
+  Phase reads specs only, never code; no project-wide search (grep / find / ripgrep)
+  outside the reads explicitly listed by the directive. `audit` is the only directive
+  permitted to read code; it alone resolves spec/code mismatch.
+</Axiom>

package/ai/kit/axiom/truth/ax-stale-must-be-rejected.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/dev-review.directive.xml -->
+<Axiom id="AX_STALE_MUST_BE_REJECTED">If finding's fact no longer holds in current HEAD → mark `rejected-stale`.</Axiom>

package/ai/kit/axiom/typescript/ax-base-contract-shape.xml

@@ -0,0 +1,25 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_BASE_CONTRACT_SHAPE">
+Base JSDoc contract shape for all types, interfaces, methods, fields, properties, getters, setters, functions (incl. `protected`):
+
+- **Default root contract:** `@purpose` (compressed essence). Do NOT replace a root definition or implementation owner with `@see`.
+- **Root implementation rule:** exported class or const directly implementing an existing named contract keeps its own `@purpose` AND adds `@implements {InterfaceName} in path`.
+- **Member implementation rule:** `@see {InterfaceName#memberName} in path` allowed only for direct public/protected implementation or inheritance edge where behavior matches.
+- **Override rule:** override / redefinition (behavior/contract change) → write the full contract explicitly; do not rely only on `@see`.
+- **Clarification rule:** if an implementation needs its own `@consumers`, `@invariant`, `@pre`, `@throws`, `@returns`, `@post`, or `@sideEffect` because the inherited contract is being tightened/specialized/extended → treat as override; write the full explicit contract instead of mixing extra tags into a `@see`-only stub.
+- **Single-line:** `/** @purpose Verb Object Context */` or `/** @see {InterfaceName#memberName} in ./path */`.
+- **Multi-line:** for complex entities, exported implementation roots, or entities with optional tags. Strict order mandatory.
+
+**Optional JSDoc tags (order MANDATORY):**
+1. `@consumers` — who consumes the API.
+2. `@implements` — the contract root implemented.
+3. `@invariant` — constraints, SLA, retry / error policies, ordering guarantees, implementation strategy guarantees that modifying agents must preserve.
+4. `@pre` — hidden preconditions before the call.
+5. `@param` — one coherent role description. Do NOT duplicate field structure from the type.
+6. `@throws` — reason for throw / Promise rejection.
+7. `@returns` — business purpose of a successful result / Promise resolution.
+8. `@post` — state guarantees after the call.
+9. `@sideEffect` — I/O, network, logs, etc.
+
+A strict order and closed vocabulary let a reader-agent parse the JSDoc contract deterministically. File-level tags (`@file:`, `@consumers:`, `@tasks:`) live in `// @tag:` line-comments at file head — never inside entity JSDoc (see `AX_FILE_LEVEL_CONTEXT`).
+</Axiom>

package/ai/kit/axiom/typescript/ax-consumers-tag-semantics.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_CONSUMERS_TAG_SEMANTICS">
+      `@consumers:` names the entity (class, function, interface) that depends on this file's primary exports — not a file path, not a folder name. Name MUST match the consuming entity as named in the spec.
+    </Axiom>

package/ai/kit/axiom/typescript/ax-direct-implementation-protocol.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_DIRECT_IMPLEMENTATION_PROTOCOL">
+Mandatory protocol for direct implementations of a contract. For every exported runtime root that directly implements a named contract:
+1. Keep the root-level `@purpose` (compressed essence).
+2. Add `@implements {ContractName} in path` on the root.
+3. Add `@see {ContractName#memberName} in path` on every direct public/protected implementation member, unless that member is a true override with a full explicit contract.
+
+Do not stop at the TS `implements` keyword, owner-level class JSDoc, or method «obviousness». These links are mandatory contract edges, not decoration. Without them a reader-agent does not see the implementation→contract link without grep; a member without `@see` is indistinguishable from an override.
+</Axiom>

package/ai/kit/axiom/typescript/ax-english-only-names-and-comments.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_ENGLISH_ONLY_NAMES_AND_COMMENTS">
+Test titles, comments, anchors, helper variable names — English only. Mixed languages break grep and comprehension.
+</Axiom>

package/ai/kit/axiom/typescript/ax-entity-specific-minimums.xml

@@ -0,0 +1,11 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_ENTITY_SPECIFIC_MINIMUMS">
+Minimum requirements per entity kind:
+- **Exported data shapes:** `type` + `@purpose`; use `@consumers` only when consumer diverges from the file-level context declaration.
+- **Pure alias / shape-forwarding exports** with no runtime behavior may use a root-level `@see`. But runtime-bearing class/const implementations do NOT replace their owner contract with `@see`.
+- **Service interfaces / external-system clients:** require `@invariant` for error policy, retry policy, ordering guarantees, rate limits, or other resilience constraints.
+- **Implementations of an existing runtime contract:** owner-level `@purpose` on class/const + `@implements {ContractName} in path` on root + `@see {ContractName#memberName} in path` on each public/protected member when behavior matches.
+- **Async functions / methods:** `@returns` describes the resolved value; `@throws` describes the rejected/throw path; `@sideEffect` documents external action when present.
+- **Exported config constants:** `@invariant` when value bounds or combinations must remain stable.
+- **Within one implementing surface** `@implements` and member-level `@see` MUST use same path style and same contract names — do not mix local-relative and project-root-relative references inside one module.
+</Axiom>

package/ai/kit/axiom/typescript/ax-flat-jsdoc-for-properties.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_FLAT_JSDOC_FOR_PROPERTIES">
+Single-line JSDoc for properties. When defining properties inside `type`, `interface`, or DTOs, generate the JSDoc as a single flat string to preserve vertical density. If multiple tags are required, merge them on the same line using the ` | ` separator. Example: `/** @purpose Smallest id in the range | @invariant >= 0 */`. Multi-line JSDoc blocks are strictly reserved for module roots, classes, and methods.
+
+` | ` separates distinct JSDoc **tags**, not continuation lines of one tag. A multi-sentence `@purpose` is compressed to one sentence — not joined with ` | `. Discard sentences that restate the property name or explain the obvious; keep only the constraint or role that cannot be inferred from the type.
+</Axiom>

package/ai/kit/axiom/typescript/ax-implementation-hiding-in-public.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_IMPLEMENTATION_HIDING_IN_PUBLIC">
+Public methods do not leak implementation. Forbidden infrastructure words in public APIs: `Db`, `Sql`, `Http` (exception: serializer layers, where this IS the contract). Leaking transport into a public name breaks Ports & Adapters and binds consumers to a concrete implementation.
+</Axiom>

package/ai/kit/axiom/typescript/ax-no-transpile-only-constructs.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_NO_TRANSPILE_ONLY_CONSTRUCTS">
+Forbid transpile-only syntax. `enum`, `namespace`, and constructor parameter properties (`constructor(private foo: string)`) are forbidden. Native Node.js supports only type stripping; these constructs require AST-to-JS transforms and reliably fail with `SyntaxError` at runtime.
+
+Alternatives: string literal unions (`'a' | 'b'`) or `const + as const` instead of `enum`; assign constructor fields explicitly inside the body.
+</Axiom>

package/ai/kit/axiom/typescript/ax-tag-usage-matrix.xml

@@ -0,0 +1,15 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_TAG_USAGE_MATRIX">
+When each tag is used:
+- `@file:`, `@tasks:` — file-level line-comments only; see `AX_FILE_LEVEL_CONTEXT`.
+- `@consumers` — file-level line-comment when uniform; entity-level only when consumer diverges from file-level; skip for local helpers.
+- `@implements` — required on exported class/const root directly implementing a named interface/contract; skip for data shapes, interfaces, member declarations.
+- `@invariant` — stateful entities, resilience / error policy, ordering guarantees, non-local assumptions, implementation-strategy guarantees that modifying agents must preserve.
+- `@pre` — ONLY for hidden environment / system-state preconditions not captured by the type signature.
+- `@param` — when arguments exist; one coherent role description; do NOT enumerate object fields already in the type.
+- `@throws` — when the function can throw / reject; describe failure reason, not generic possibility.
+- `@returns` — for non-void / non-never results; describe WHY the caller needs the value, not the TS shape.
+- `@post` — state guarantees not already encoded by `@returns`, types, or obvious control flow.
+- `@sideEffect` — externally visible effects (network, fs, process, shared-state mutation, emitted events). Routine debug logging alone does NOT justify the tag.
+- `@see` — ONLY for direct member implementation / inheritance of an existing contract; do NOT use as a root class/const tag when root owns runtime behavior. Behavior diverges → write the full contract.
+</Axiom>

package/ai/kit/axiom/typescript/ax-truthful-encapsulation.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_TRUTHFUL_ENCAPSULATION">
+Truthful encapsulation, not false. Native private fields (`#field`) and the `private` modifier are forbidden. For internal state use `protected` with `_` prefix (`protected _logger`). Omit the `public` modifier.
+
+`#` blocks reflection and decorators. `private` is erased at compile time: access restriction is not enforced at runtime, and reflection / decorators observe the field as public, contradicting the declared visibility. `protected _foo` truthfully reflects runtime behavior and preserves metaprogramming hooks.
+</Axiom>

package/ai/kit/axiom/typescript/ax-type-vs-interface-choice.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_TYPE_VS_INTERFACE_CHOICE">
+Architecture-level choice. DTOs, configs, API responses → `type`. `interface` reserved for abstractions with inheritance / implementation (polymorphism). A consistent choice makes a type's intent readable at a glance: `interface` signals «polymorphism point»; `type` signals «data shape».
+</Axiom>

package/ai/kit/axiom/uikit/ax-a11y-audit-parameters.xml

@@ -0,0 +1,14 @@
+<!-- source: ai/directives/coding/uikit-component-storybook.xml -->
+<Axiom id="AX_A11Y_AUDIT_PARAMETERS">
+      Every story carries `parameters: { a11y: { test: 'error' } }`. This enables the `@storybook/addon-a11y` to run axe-core automatically during `run-story-tests`. A violation at `error` level fails the story run.
+
+      The parameter can be set at the `meta` level to apply to all stories:
+      ```typescript
+      const meta: Meta<typeof Button> = {
+        component: Button,
+        tags: ['autodocs'],
+        parameters: { a11y: { test: 'error' } },
+      };
+      ```
+      Individual stories can override with stricter config but never less strict.
+    </Axiom>

package/ai/kit/axiom/uikit/ax-a11y-defaults.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/coding/uikit-spec-drafting.xml -->
+<Axiom id="AX_A11Y_DEFAULTS">
+      Default a11y requirements for common component types. Apply the template matching the component type.
+
+      For **button:**
+      - **Role:** button
+      - **aria-label:** формируется из label + counter (если есть)
+      - **aria-disabled:** при state=disabled
+      - **Keyboard:** Enter, Space активируют кнопку
+
+      For **other interactive components** (checkbox, radio, link, input): infer role from component name and visual structure; apply standard WAI-ARIA patterns.
+</Axiom>

package/ai/kit/axiom/uikit/ax-a11y-requirements.xml

@@ -0,0 +1,18 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_A11Y_REQUIREMENTS">
+Every interactive uikit component MUST declare:
+- `role` — WAI-ARIA role (button, checkbox, etc.).
+- `aria-label` — computed from label + counter (when present).
+- `aria-disabled` — bound to the disabled state.
+- `tabindex` — `0` when interactive, `-1` when disabled.
+- Keyboard support — Enter and Space for activation.
+
+For Button specifically:
+- `role="button"`
+- `aria-label={label}` (plus counter if present: `` `${label} ${counter}` ``)
+- `aria-disabled={disabled}`
+- `aria-pressed={state === 'active'}` (optional, for toggle mode)
+- `tabindex={disabled ? -1 : 0}`
+
+Focus styles use `:focus-visible` with appearance-dependent styling. No custom focus ring that overrides the browser default without providing equivalent visual feedback.
+</Axiom>

package/ai/kit/axiom/uikit/ax-component-props-contract.xml

@@ -0,0 +1,20 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_COMPONENT_PROPS_CONTRACT">
+A uikit component receives its variant configuration through Svelte 5 `$props()` destructuring. The prop surface matches the spec's Variants table columns:
+
+```typescript
+let {
+    appearance = 'accent',
+    mode = 'primary',
+    size = 's',
+    state = 'normal',
+    icon = false,
+    label = '',
+    counter = undefined,
+    indicator = false,
+    disabled = false,
+}: Props = $props();
+```
+
+The `disabled` prop takes precedence over `state` — when `disabled={true}`, `data-state` is `disabled` regardless of the `state` prop value. The component derives `aria-disabled` and `tabindex` from `disabled`.
+</Axiom>

package/ai/kit/axiom/uikit/ax-css-module-selector-conventions.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_CSS_MODULE_SELECTOR_CONVENTIONS">
+CSS module selectors follow the data-attribute pattern consistently:
+- `.btn[data-size="s"]` for size-dependent styles.
+- `.btn[data-mode="primary"][data-appearance="accent"]` for mode × appearance combinations.
+- `.btn[data-state="hover"]` for state-dependent styles.
+- Child elements use class selectors: `.icon`, `.label`, `.counter`, `.indicator`.
+
+No ID selectors, no tag selectors (except `:root` in tokens), no descendant selectors deeper than 2 levels. Every selector is scoped to the component's root class (`.btn`).
+</Axiom>

package/ai/kit/axiom/uikit/ax-css-tokens-via-root.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_CSS_TOKENS_VIA_ROOT">
+CSS custom properties (design tokens) are inherited through `:root` in `<name>.tokens.css`. Shadow DOM is NOT used for token inheritance — the component relies on the global CSS cascade.
+
+The tokens file has two mandatory blocks:
+1. `:root { ... }` — the token declarations block.
+2. Override block — tokens where the SVG value differs from the VKUI default, each with a `/* override: was Xpx */` comment.
+
+The CSS module (`<name>.module.css`) consumes these tokens via `var(--vkui--...)` functions. No hardcoded pixel values in `.module.css` — every dimension, color, and spacing comes from a token.
+
+Counter element: `box-sizing: border-box` is mandatory (prevents overflow when the counter number grows).
+</Axiom>

package/ai/kit/axiom/uikit/ax-data-attrs-not-host.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_DATA_ATTRS_NOT_HOST">
+CSS selectors use `data-*` attributes on an inner wrapper element, NOT `:host()` pseudo-class selectors. The outer host element is a simple `display: inline-block` container; all styling and testable selectors target the inner element.
+
+Reasoning (D-UC01): `:host([attr="value"])` compound selectors fail in headless Chromium — `getComputedStyle` returns `0px` for padding. The inner-wrapper approach with `data-*` attributes is proven in the Button PoC and works consistently across all test environments.
+
+Correct pattern:
+```css
+.btn[data-mode="primary"] { ... }
+.btn[data-appearance="accent"] { ... }
+.btn[data-size="s"] { height: var(--vkui--size_button_small_height--compact); }
+.btn[data-state="hover"] { /* hover styles */ }
+```
+
+Forbidden: `:host([mode="primary"])`, `:host(.primary)`, any `:host()` usage.
+</Axiom>

package/ai/kit/axiom/uikit/ax-data-state-for-testability.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_DATA_STATE_FOR_TESTABILITY">
+Every interactive state that is normally expressed through a CSS pseudo-class (`:hover`, `:active`, `:disabled`) MUST also be expressed through a `data-state` attribute on the inner wrapper element. CSS pseudo-classes cannot be triggered programmatically in headless test environments — `data-state` provides the testable channel.
+
+States: `normal`, `hover`, `active`, `disabled`. The `data-state` attribute is always present, never conditionally omitted. The component derives `data-state` from the `state` prop, not from browser events.
+
+For test assertions: `expect(element).toHaveAttribute('data-state', 'hover')` — NOT `expect(element).toHaveStyle(...)` for pseudo-class-triggered styles (that won't work in headless).
+</Axiom>

package/ai/kit/axiom/uikit/ax-element-structure-from-extraction.xml

@@ -0,0 +1,13 @@
+<!-- source: ai/directives/coding/uikit-spec-drafting.xml -->
+<Axiom id="AX_ELEMENT_STRUCTURE_FROM_EXTRACTION">
+      The Element Structure section is derived from `ExtractionResult.elements` — the list of element names discovered in the SVG.
+
+      Procedure:
+      1. Map each element name to a semantic description:
+         - `icon` → "SVG-иконка (обрезанный viewBox до tight path bounds)"
+         - `label` → "текстовая метка"
+         - `counter` → "числовой счётчик (box-sizing: border-box)"
+         - `indicator` → "шеврон (стрелка вправо)"
+      2. For unknown element names: infer from context, mark with `⚠️ requires clarification`.
+      3. Order elements: icon, label, counter, indicator (visual left-to-right).
+</Axiom>

package/ai/kit/axiom/uikit/ax-existing-components-check.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/sdd/svelte-ui-discovery.directive.xml -->
+<Axiom id="AX_EXISTING_COMPONENTS_CHECK">
+      Перед созданием нового компонента — проверить существующие. Шаг 0:
+      - Есть ли в `specs/<scope>/components/` спека с похожим именем?
+      - Можно ли собрать нужный вариант из existing компонента (композиция)?
+      - Можно ли доработать existing (добавить mode/appearance/size)?
+
+      Если existing подходит — не создаём новый, а запускаем refine existing. Результат фиксируется в Decision Log.
+    </Axiom>

package/ai/kit/axiom/uikit/ax-extraction-input.xml

@@ -0,0 +1,15 @@
+<!-- source: ai/directives/coding/uikit-spec-drafting.xml -->
+<Axiom id="AX_EXTRACTION_INPUT">
+      The input is an `ExtractionResult` object with shape:
+      ```json
+      {
+        "component": "button",
+        "svg": "<path-to-svg>",
+        "variants": [ /* SvgVariant[] */ ],
+        "elements": [ "icon", "label", "counter", "indicator" ],
+        "tokenOverrides": [ /* TokenCandidate[] where match=false */ ]
+      }
+      ```
+      Every `SvgVariant` carries: `id`, `size`, `appearance`, `mode`, `state`, and `measurements` (MeasurementSet with height, width, leftPad, rightPad, borderRadius, rectFill, elements).
+      Every `TokenCandidate` carries: `metric`, `svgValue`, `token`, `tokenValue`, `diff`, `match`.
+</Axiom>

package/ai/kit/axiom/uikit/ax-file-structure-kebab-case.xml

@@ -0,0 +1,13 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_FILE_STRUCTURE_KEBAB_CASE">
+Every uikit component consists of EXACTLY four files, all in kebab-case, all in a single directory `src/ui/<name>/`:
+
+| File                     | Purpose                                        |
+|--------------------------|------------------------------------------------|
+| `<name>.svelte`           | Svelte component (data-attributes, a11y)       |
+| `<name>.module.css`       | CSS module (data-attribute selectors)          |
+| `<name>.tokens.css`       | `:root` + override tokens                      |
+| `<name>.stories.ts`       | Storybook stories (mirror of spec)             |
+
+No PascalCase (`Button.svelte`), no camelCase (`buttonModule.css`), no additional files (`button.utils.ts` belongs elsewhere or doesn't exist). The four-file set is the closed-world contract per `ComponentArtefact`.
+</Axiom>

package/ai/kit/axiom/uikit/ax-icon-svg-tight-viewbox.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_ICON_SVG_TIGHT_VIEWBOX">
+SVG icons have their viewBox cropped to the tight bounding box of the path — NOT the 20×20 Figma container. This prevents unwanted whitespace around icons and ensures consistent spacing within the button.
+
+The icon SVG is inlined (not an `<img>` tag) so its fill color can be controlled via CSS. Icon fill inherits from the button's current appearance/mode color.
+</Axiom>

package/ai/kit/axiom/uikit/ax-token-discipline.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/sdd/svelte-ui-discovery.directive.xml -->
+<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>

package/ai/kit/axiom/uikit/ax-token-override-comment.xml

@@ -0,0 +1,11 @@
+<!-- source: ai/directives/coding/uikit-component-svelte.xml -->
+<Axiom id="AX_TOKEN_OVERRIDE_COMMENT">
+Every token override (where `diff > 1px` between SVG measurement and VKUI default) MUST carry a comment in `.tokens.css`:
+
+```css
+/* override: was 8px */
+--vkui--size_button_tertiary_small_padding_horizontal_icon--regular: 14px;
+```
+
+The comment format is: `/* override: was <original-value> */`. This preserves the audit trail — an operator or SpecValidator can verify that the override was intentional and trace it back to the Token Mapping table in the spec.
+</Axiom>

package/ai/kit/axiom/uikit/ax-token-section-generation.xml

@@ -0,0 +1,13 @@
+<!-- source: ai/directives/coding/uikit-spec-drafting.xml -->
+<Axiom id="AX_TOKEN_SECTION_GENERATION">
+      The Token Mapping section populates measurements from `ExtractionResult.variants[].measurements` and maps them to VKUI tokens from `TokenCandidate[]`.
+
+      Procedure:
+      1. Collect all unique `(element, metric)` pairs across all variants. The `element` prefix is derived from `MeasurementSet` fields: `icon-padding-left` (from leftPad of icon element), `height`, `border-radius`, etc.
+      2. For each pair, find the corresponding `TokenCandidate` where exists. If not found → mark as `⚠️ no token`.
+      3. Compute `diff = |svgValue - tokenValue|`.
+      4. If `diff ≤ 1` → Action = `OK`. If `diff > 1` → Action = `OVERRIDE: &lt;svgValue&gt;px`.
+      5. Sort rows: element name alphabetically.
+
+      Note: `ExtractionResult.tokenOverrides` contains only candidates where `match: false`. For the full Token Mapping table, you need ALL measurements — both matched and unmatched. If `tokenOverrides` is the only source, the table will be incomplete. Prefer deriving measurements from `variants[].measurements` and cross-referencing with token mappings.
+</Axiom>

package/ai/kit/axiom/uikit/ax-variant-grouping.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/coding/uikit-spec-drafting.xml -->
+<Axiom id="AX_VARIANT_GROUPING">
+      Variants are grouped hierarchically: `size → appearance → mode`. Each leaf group contains all 4 states (normal, hover, active, disabled). The result is a closed-world table — every combination is listed explicitly, no «и т.д.» allowed.
+
+      Procedure:
+      1. Collect all unique triples `(size, appearance, mode)` from `ExtractionResult.variants`.
+      2. Sort: size (s, m, l) → appearance (accent, neutral, contrary) → mode (primary, secondary, tertiary, outline).
+      3. For each triple, list states: `normal, hover, active, disabled`.
+      4. If a state is missing from the extraction data, mark it as `⚠️ not in extraction` — do NOT omit the row.
+</Axiom>

package/ai/kit/build-directives.ts

@@ -0,0 +1,39 @@
+/**
+ * Build ai/directives/*.xml from Handlebars templates under ai/kit/templates/.
+ * Static build: each template rendered with empty data. Dynamic tools call render() with params.
+ * Run: npm run build:directives
+ *
+ * Flags:
+ *   --check       render + lint only, write nothing (alias: --dry-run)
+ *   --out=<dir>   write rendered files under <dir> instead of ai/directives
+ *
+ * After rendering, the dangling-axiom lint (lint-axioms.ts) runs over the whole output and
+ * prints warnings (never fails the build) — see AUTHORING.md §7.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+import { createRenderer, walk, TEMPLATES, OUT_ROOT } from './render.ts';
+import { lintDanglingAxioms, formatDanglingReport, type RenderedDirective } from './lint-axioms.ts';
+
+const args = process.argv.slice(2);
+const checkOnly = args.includes('--check') || args.includes('--dry-run');
+const outRoot = args.find((a) => a.startsWith('--out='))?.slice('--out='.length) ?? OUT_ROOT;
+
+const { render } = createRenderer();
+
+const rendered: RenderedDirective[] = [];
+for (const t of walk(TEMPLATES, (p) => p.endsWith('.hbs'))) {
+  const rel = relative(TEMPLATES, t).replace(/\.hbs$/, '.xml');
+  const out = render(readFileSync(t, 'utf8'));
+  rendered.push({ file: rel, text: out });
+  if (!checkOnly) {
+    const dest = join(outRoot, rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, out);
+  }
+  console.log(`${checkOnly ? '·' : '✓'} ${rel}`);
+}
+console.log(`\n${checkOnly ? 'Checked' : 'Generated'} ${rendered.length} directive(s).`);
+
+const report = formatDanglingReport(lintDanglingAxioms(rendered));
+if (report) console.warn(`\n${report}`);

package/ai/kit/contract/audit/audit-session-summary-format.xml

@@ -0,0 +1,38 @@
+<!-- source: sdd/audit.directive.xml -->
+<Contract id="AUDIT_SESSION_SUMMARY_FORMAT">
+      **Compact AI-to-AI inline format.** Ephemeral output at session end. One header line + one line per finding + optional applied-changes lines. No markdown tables, no decorative prose. Designed so the next agent (or operator's tooling) parses it in one pass.
+
+      Grammar (one logical record per line, EOL-terminated; fields separated by ` | `):
+
+      ```
+      @audit task=<Task-ID> round=<N> mode=<per-task|epic> status=<PASS|PASS_RISK|FAIL> counts=B<n>·M<n>·m<n>·I<n> phases_to_fix=[<P<N>>,...]
+      F-<NN> | sev=<B|M|m|I> | type=<TYPETOKEN> | conf=<H|M|L> | loc=<path:line|—> | phase=<P<N>|—> | src=<spec/ticket/rule anchor|—> | route=<spec-edit|ticket-reopen|ticket-update|decision-log|code-fix> | act=<one-line action, no newlines>
+      F-<NN> | …
+      ~applied | <target> | <one-line description of inline change>   (optional, repeat per applied change)
+      ```
+
+      Token vocabulary:
+      - `sev`: `B`=BLOCKER, `M`=MAJOR, `m`=MINOR, `I`=INFO.
+      - `conf`: `H`=HIGH, `M`=MEDIUM, `L`=LOW.
+      - `type`: one of `CLOSED_WORLD_DRIFT` | `COMPLETENESS_GAP` | `RUNTIME_BACKING_VIOLATION` | `RULES_COMPLIANCE_VIOLATION` | `RULES_CASCADE_MISMATCH` | `TASK_ID_DRIFT` | `BDD_COVERAGE_MISMATCH` | `EXECUTION_LOG_INCOMPLETE` | `STALE_AFTER_PIVOT` | `INSIGHT_BACKFLOW`.
+      - `route`: one of `spec-edit` | `ticket-reopen` | `ticket-update` | `decision-log` | `code-fix` (per `AX_FINDING_ROUTING`).
+      - `act` text: Russian operator-facing per `AX_OPERATOR_LANGUAGE` (this is operator-facing artifact prose), single line, no pipe character.
+      - `status` `PASS_RISK` = PASS_WITH_ACKNOWLEDGED_RISKS.
+
+      Example:
+      ```
+      @audit task=TSK-04 round=3 mode=per-task status=FAIL counts=B1·M2·m0·I1
+      F-01 | sev=B | type=CLOSED_WORLD_DRIFT | conf=H | loc=src/payments/adapter.ts:42 | src=specs/backend/payments/payments.spec.md#2 | route=spec-edit | act=добавить `IdempotencyKey` в Entity Inventory модуля payments
+      F-02 | sev=M | type=RULES_COMPLIANCE_VIOLATION | conf=H | loc=src/payments/adapter.ts:100 | src=ai/directives/coding/typescript-rules.xml#AX_STRICT_NULL | route=ticket-reopen | act=добавить null-guard на response.balanceTransaction
+      F-03 | sev=M | type=BDD_COVERAGE_MISMATCH | conf=H | loc=src/payments/adapter.test.ts:55 | src=tasks/backend/payments/payments.task-04.md#4 | route=ticket-update | act=переименовать тест-кейс в `should reject non-positive amount with InvalidAmountError`
+      F-04 | sev=I | type=INSIGHT_BACKFLOW | conf=M | loc=src/payments/adapter.ts:88 | src=specs/backend/payments/payments.spec.md#4 | route=spec-edit | act=зафиксировать retry-budget в DbC postcondition
+      ~applied | specs/backend/payments/payments.spec.md2 | добавлен `IdempotencyKey` в Entity Inventory
+      ```
+
+      Rules:
+      - First line MUST be the `@audit` header. No prose preamble.
+      - Findings ordered by descending severity, then by `F-NN`.
+      - No empty lines inside the block.
+      - If `loc` or `src` is N/A, emit literal `—` (em-dash) — do not omit the field.
+      - `act` is operator-facing prose (Russian per policy); everything else is English tokens.
+    </Contract>

package/ai/kit/contract/audit/finding-format.xml

@@ -0,0 +1,20 @@
+<!-- source: sdd/audit.directive.xml -->
+<Contract id="FINDING_FORMAT">
+      ```markdown
+      ### <🔴|🟠|🟡|🔵> F-NNN — <short title>
+      - **Type:** CLOSED_WORLD_DRIFT | COMPLETENESS_GAP | RUNTIME_BACKING_VIOLATION | RULES_COMPLIANCE_VIOLATION | RULES_CASCADE_MISMATCH | TASK_ID_DRIFT | BDD_COVERAGE_MISMATCH | EXECUTION_LOG_INCOMPLETE | STALE_AFTER_PIVOT | INSIGHT_BACKFLOW
+      - **Severity:** 🔴 BLOCKER | 🟠 MAJOR | 🟡 MINOR | 🔵 INFO
+      - **Confidence:** HIGH | MEDIUM | LOW
+      - **Status:** 📂 open | ⚠️ operator-acknowledged | ✅ resolved
+      - 📍 **Location:** `<path>:<line>` if applicable
+      - 💬 **Detail:** <factual description, no value words>
+      - 🔗 **Source-of-truth:** link to spec section / ticket section / rule axiom
+      - 📝 **Proposed Remediation:**
+        - Type: `code-fix` | `spec-update` | `ticket-update`
+        - Action: <concrete proposal, with diff if possible>
+        - Routing: <per AX_FINDING_ROUTING — where this change goes>
+      ```
+      F-NNN IDs unique per audit session; do not reuse.
+
+      Usage: this verbose form is for in-session discussion / deep dive only. The canonical machine-readable record at session end is the compact `AUDIT_SESSION_SUMMARY_FORMAT`. Do NOT emit `FINDING_FORMAT` blocks in the final summary.
+    </Contract>

package/ai/kit/contract/audit/ticket-audit-round-format.xml

@@ -0,0 +1,38 @@
+<!-- source: sdd/audit.directive.xml -->
+<Contract id="TICKET_AUDIT_ROUND_FORMAT">
+      Appended to the ticket file as a `## Audit Rounds` section (created on first reopen-triggering audit; subsequent audits append `### Audit Round N` entries). Same compact AI-to-AI inline grammar as `AUDIT_SESSION_SUMMARY_FORMAT` — the ticket carries the canonical audit record machines can re-parse later.
+
+      Shape inside the ticket:
+
+      ```markdown
+      ## Audit Rounds
+
+      ### Audit Round <N> — <YYYY-MM-DD>, after Execution Round <M>
+      ```
+      @audit task=<Task-ID> round=<N> after-exec-round=<M> triggered-reopen=<Round-M+1|none> status=<FAIL|PASS_RISK> counts=B<n>·M<n>·m<n>·I<n>
+      F-NN | sev=… | type=… | conf=… | loc=… | src=… | route=… | act=…
+      …
+      ~applied | <target> | <one-line description>
+      ```
+      ```
+
+      Concrete example (inside a ticket file):
+
+      ```markdown
+      ## Audit Rounds
+
+      ### Audit Round 1 — 2026-05-12, after Execution Round 1
+      ```
+      @audit task=TSK-04 round=1 after-exec-round=1 triggered-reopen=Round-2 status=FAIL counts=B1·M1·m0·I0
+      F-01 | sev=B | type=CLOSED_WORLD_DRIFT | conf=H | loc=src/payments/adapter.ts:42 | src=specs/backend/payments/payments.spec.md#2 | route=spec-edit | act=добавить `IdempotencyKey` в Entity Inventory
+      F-02 | sev=M | type=RULES_COMPLIANCE_VIOLATION | conf=H | loc=src/payments/adapter.ts:100 | src=ai/directives/coding/typescript-rules.xml#AX_STRICT_NULL | route=ticket-reopen | act=добавить null-guard на response.balanceTransaction
+      ~applied | specs/backend/payments/payments.spec.md2 | добавлен `IdempotencyKey` в Entity Inventory
+      ```
+      ```
+
+      Constraints:
+      - Append-only. Prior `### Audit Round` entries are immutable (mirrors Round-immutability in `phase-execution-protocol`).
+      - PASS audits without reopen are NOT written here — output stays ephemeral.
+      - `N` increments monotonically across the ticket's lifetime, independent of Execution Round numbers.
+      - The fenced code block inside each round is the same compact grammar as `AUDIT_SESSION_SUMMARY_FORMAT` — machines parse it without rewriting.
+    </Contract>

package/ai/kit/contract/critic/oc-structured.xml

@@ -0,0 +1,2 @@
+<!-- source: sdd/critic-protocol.xml -->
+<Contract id="OC_STRUCTURED">Exact headers: "## What I understood", "## What I did NOT understand", "## Problems found", "## Verdict". No greetings, no sign-off. Machine-parseable.</Contract>

package/ai/kit/contract/interview/coverage-map-format.xml

@@ -0,0 +1,12 @@
+<!-- source: new for sdd-v2 interview protocol; rendering from ai/skills/prd-interview -->
+<Contract id="COVERAGE_MAP_FORMAT">
+  Live coverage map, shown to the operator compactly before every round. Topic labels in Russian;
+  ≤ 72 columns; statuses: `[✔]` closed · `[▶]` in progress · `[ ]` open · `[✗ skip: <причина>]`.
+
+  Покрытие: Цель/не-цель [✔] · Потребители [▶] · Слабые места [ ] · Зависимости [ ]
+  Усиления:  security [▶] · storage [✗ skip: прототип, данных нет]
+
+  4–6 topics per line; the «Усиления» line appears only when at least one amplification is
+  active or skipped. The map is session state for the dialogue — the calling step decides what
+  from the answers lands in the artifact; the map itself stays out of the spec.
+</Contract>

package/ai/kit/contract/process/blocker-format.xml

@@ -0,0 +1,9 @@
+<!-- source: sdd/phase-execution-protocol.xml -->
+<Contract id="BLOCKER_FORMAT">
+      ```markdown
+      - 🛑 `<ts>` BLOCKED: <one-line cause>
+        - 🔗 axiom: AX_<NAME>
+        - 💬 unblock: <concrete operator action>
+      ```
+      After this entry: phase Status → `[!] BLOCKED`; return BLOCKED to orchestrator. Stop.
+    </Contract>

package/ai/kit/contract/process/breadcrumb-format.xml

@@ -0,0 +1,8 @@
+<!-- source: sdd-opt-v1 BREADCRUMB_FORMAT -->
+<Contract id="BREADCRUMB_FORMAT">
+  One line under the service line: this session's milestones, each with a status marker — `✅` done
+  · `▶️` now · `░` not yet. Delta only; never re-list everything already settled. This is the
+  «where are we», and it replaces a verbose run-on of finished steps.
+
+  `<Веха>` ✅ · `<Веха>` ✅ · `<Веха>` ▶️ · `<Веха>` ░ · `<Веха>` ░
+</Contract>

package/ai/kit/contract/process/execute-summary-format.xml

@@ -0,0 +1,11 @@
+<!-- source: sdd-execute skill final summary -->
+<Contract id="EXECUTE_SUMMARY_FORMAT">
+  Final operator summary once audit settles. Plain, scannable:
+
+  📊 Task `<Task-ID>` — Execute + Audit
+  🔧 Round 1: `P1 (impl, sonnet) ✅` · `P2 (test, haiku) ✅` · …
+  🔍 Round 1 audit: `✅ PASS` | `❌ FAIL (🔴 N · 🟠 M)`
+  🔄 Round 2 (if any): `P2 (fix) ✅` · audit R2 `✅`
+  📊 Final: `✅ PASS` | `⚠️ PASS_WITH_ACKNOWLEDGED_RISKS` | `❌ FAIL`
+  ⏱️ wall total · 📍 files touched · ⚠️ problems encountered
+</Contract>

package/ai/kit/contract/process/fix-summary-format.xml

@@ -0,0 +1,23 @@
+<!-- source: sdd/fix.directive.xml -->
+<Contract id="FIX_SUMMARY_FORMAT">
+      ```
+      ## ✅ sdd-fix complete
+
+      Trivial fixes: N applied            <!-- STEP_2B short-circuit only: patch + its regression test, one grouped entry -->
+        ✅ <what> (+ regression test) → <file>
+
+      Direct fixes: N applied
+        ✅ <what> → <file>
+        ✅ <what> → <file>
+
+      Spec updates: N applied
+        ✅ <what> → <file>
+
+      Tasks reopened: N
+        🔄 TSK-NN — Round N: <reason> → dispatched
+        🔄 TSK-MM — Round N: <reason> → dispatched
+
+      🔍 sdd-check: ✅ PASS (N/N checks)   <!-- full path; the trivial branch reports its light gate here instead: `🔍 light gate: typecheck ✅ · tests ✅ (N/N)` — a red pre-existing gate is reported per the branch rule, and the header then must NOT read "complete" -->
+      ```
+      Omit any section whose count is 0. Every file changed on disk MUST appear under exactly one section — a summary whose counts are all zero while the diff is non-empty is a defective summary.
+    </Contract>

package/ai/kit/contract/process/flow-diagram-when.xml

@@ -0,0 +1,12 @@
+<!-- source: sdd-opt-v1 FLOW_DIAGRAM_WHEN -->
+<Contract id="FLOW_DIAGRAM_WHEN">
+  When a decision is about a flow — data moving, state transitions, start / stop conditions — draw
+  a tiny ASCII diagram; one glance beats a paragraph. This is the one place a fenced block is
+  allowed inside an operator message (alignment matters). Keep it small.
+
+  ```
+  [сеть] [auth] [конфиг]  ──всё есть──►  ОПРОС идёт
+          ▲                                  │
+          └──── снова есть ──── ПАУЗА ◄───────┘  что-то пропало
+  ```
+</Contract>