gennady 0.8.3 → 0.8.4-draft.2

package/dist/ai/kit/axiom/svelte/ax-sk-data-via-load.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_DATA_VIA_LOAD">
+Data needed to render a route is fetched in `load()` — universal in `+page.ts` / `+layout.ts`, server-only in `+page.server.ts` / `+layout.server.ts`. The return shape becomes `data` on the page (`let { data } = $props()`).
+
+Forbidden as default: calling `fetch` from a component `<script>` to populate initial state. Component-level fetch loses SSR, breaks invalidation, and bypasses the server's privileged access. Reserved exception: client-only progressive updates that have NO server data dependency.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-fetch-from-load-uses-sdk-fetch.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_FETCH_FROM_LOAD_USES_SDK_FETCH">
+Inside `load` / `actions`, use the `fetch` provided by SvelteKit's event (`async ({ fetch }) => ...`), not the global `fetch`. The event-provided `fetch` propagates credentials, runs in-process for internal API routes, and inherits the user's request context. Using global `fetch` from a server `load` is a silent loss of context.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-hooks-own-cross-cutting.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_HOOKS_OWN_CROSS_CUTTING">
+Cross-cutting server concerns (auth, request enrichment, error reporting) live in `src/hooks.server.ts` via `handle({ event, resolve })`. Auth context is attached to `event.locals` and read downstream by `load` / `actions`. `handleError({ error, event })` is the single point that maps unhandled exceptions to the user-facing shape.
+
+Client-side cross-cutting goes in `src/hooks.client.ts`. Per-route boilerplate (re-checking auth in every `load`) is forbidden — `event.locals` is the contract for «who is the caller».
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-mutations-via-actions.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_MUTATIONS_VIA_ACTIONS">
+State mutations from the browser go through form `actions` in `+page.server.ts`: `export const actions = { default: async ({ request, cookies, locals, fetch }) => { ... } }`. The page submits `<form method="POST" use:enhance>` — progressive enhancement gives a working flow even without JavaScript.
+
+`fetch('/api/...', { method: 'POST' })` from a component to mutate state is forbidden as the default path. It re-implements what actions already give (CSRF, redirect, validation result) and reintroduces the server/client boundary problem one route at a time.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-page-options-per-route.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_PAGE_OPTIONS_PER_ROUTE">
+Page-level toggles (`export const ssr`, `export const prerender`, `export const csr`, `export const trailingSlash`) live in the route's `+page.ts` / `+page.server.ts` / `+layout.ts`. They are NOT global config in `svelte.config.js`.
+
+Forcing `ssr = false` globally turns a SvelteKit app into a single-page app and discards most of the framework's value; doing it per-route documents the trade-off where it applies.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-project-layout.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_PROJECT_LAYOUT">
+Canonical layout: `src/routes/` for routes, `src/lib/` for shared client+server code, `src/lib/server/` for server-only code, `src/hooks.server.ts` / `src/hooks.client.ts` for hooks, `src/app.html` for the HTML shell, `src/app.d.ts` for ambient types, `static/` for unprocessed assets. The `$lib` alias points to `src/lib`; `$lib/server` is automatically server-only.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-routing-is-file-based.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_ROUTING_IS_FILE_BASED">
+Routes are declared by directory structure under `src/routes/`. A path like `src/routes/user/[id]/+page.svelte` exposes `/user/:id`. Manual route tables, parallel router libraries, or imperative `Router` mounting are forbidden — they fork the source of truth for which URL renders what.
+
+Layout wrappers via `+layout.svelte` / `+layout.server.ts` / `+layout.ts`. Nested layouts compose; siblings do not.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-server-client-boundary.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_SERVER_CLIENT_BOUNDARY">
+The file name decides where the code runs:
+- `+page.server.ts`, `+layout.server.ts`, `hooks.server.ts`, anything under `$lib/server/` — **server-only**. Allowed to read filesystem, talk to databases, use private env.
+- `+page.ts`, `+layout.ts`, `.svelte` (instance script + template) — **universal/client**. MUST be safe to ship to the browser.
+
+Private secrets (`$env/static/private`, `$env/dynamic/private`) MUST NOT be imported from universal/client files. The toolchain refuses such imports at build time — agent's job is to keep the import graph clean from the start, not to rely on the compile error as the only guardrail.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-types-from-generated.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_TYPES_FROM_GENERATED">
+Route-specific types come from generated `./$types` modules: `PageServerLoad`, `Actions`, `PageLoad`, `LayoutData`, etc. Hand-rolling these types is forbidden — they drift the first time the route signature changes. `App.Locals`, `App.PageData`, `App.Error`, `App.Platform` are declared in `src/app.d.ts` and are the only place to extend per-app surfaces.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-sk-validation-at-action-boundary.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/sveltekit-rules.xml -->
+<Axiom id="AX_SK_VALIDATION_AT_ACTION_BOUNDARY">
+Form actions validate request input synchronously at the top, return `fail(status, payload)` on rejection. The payload is exposed as `form` on the page (`let { form } = $props()`) and re-renders the form with the offending fields preserved. Throwing arbitrary errors from an action surfaces as a 500 with no recoverable UI state — `fail()` is the contract channel.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-snippets-replace-slots.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/svelte5-runes.xml -->
+<Axiom id="AX_SNIPPETS_REPLACE_SLOTS">
+  Reusable template fragments use `{#snippet name(params)}...{/snippet}` and are invoked via `{@render name(params)}`. The Svelte 4 `<slot>` mechanism, `$$slots`, and slot props are forbidden in new components — they are removed concepts in the Svelte 5 mental model.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-conventions.xml

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

package/dist/ai/kit/axiom/svelte/ax-svelte-test-effect-root-outside-component.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_EFFECT_ROOT_OUTSIDE_COMPONENT">
+  Tests exercising `$effect` directly (not through a mounted component) MUST run inside `$effect.root(() => { ... })` and dispose of its returned cleanup. `$effect` outside a component context is illegal; `$effect.root` provides the disposal boundary that makes it legal AND that prevents effects from leaking into subsequent tests.
+
+  For component tests, `@testing-library/svelte` `render()` already establishes a component context — explicit `$effect.root` is needed only for direct rune testing in `.svelte.ts` modules.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-file-extension.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_FILE_EXTENSION">
+  Component test files use the `.svelte.test.ts` extension — the Svelte-aware Vitest convention. Plain `.test.ts` does NOT receive Svelte plugin processing; importing a `.svelte` component from such a file produces opaque compile or runtime errors. Naming is the contract that tells the toolchain «this file must go through the Svelte compiler».
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-flush-before-assert.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_FLUSH_BEFORE_ASSERT">
+  After any state mutation (user event, prop change, direct state write, simulated time advance) the test MUST call `flushSync()` from `svelte` before asserting on the DOM. `flushSync` forces pending `$effect` callbacks and DOM updates to run synchronously; without it the assertion runs against an intermediate, often stale, DOM.
+
+  Async helpers like `userEvent` may flush implicitly in some scenarios — relying on that implicit flush is fragile. Explicit `flushSync()` after the mutation is the discipline.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-inherited-vitest-rules.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_INHERITED_VITEST_RULES">
+  All Vitest discipline applies unchanged: single unified context per file, factory-over-hooks for non-lifecycle setup, file-size budget, no `vi.mock` without operator confirm, no auto snapshot updates, explicit imports from `vitest`. This directive only adds Svelte-specific overlays — it does NOT relax inherited rules.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-jsdom-environment.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_JSDOM_ENVIRONMENT">
+  The test runner environment is `jsdom` (or the equivalent browser-like environment the project standardised on). Mixing `jsdom` with `node` between files in the same suite is forbidden — one environment per project. The Svelte plugin is registered with Vitest so `.svelte` imports compile correctly during tests.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-library-for-rendering.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_LIBRARY_FOR_RENDERING">
+  Component rendering and querying go through `@testing-library/svelte`: `render(Component, { props })` for mounting; `screen.getByRole` / `getByLabelText` / `getByText` for querying. Direct `document.querySelector` / `container.querySelector` is forbidden as the default — it bypasses the accessibility-aware query layer that protects the test from CSS-coupling.
+
+  Reserved exception: an element with no semantic role AND no test-id where a selector is the only way to reach it; in that case the selector is paired with a comment naming the missing semantic.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-mount-and-cleanup.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_MOUNT_AND_CLEANUP">
+  Every component mount MUST be paired with cleanup. Either:
+  - rely on testing-library's auto-cleanup (when the Vitest config enables it), OR
+  - register `afterEach(() => cleanup())` explicitly.
+
+  Skipping cleanup leaves mounted components in the document between cases; subsequent queries return stale matches and inter-test isolation collapses.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-no-direct-dom-query.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_NO_DIRECT_DOM_QUERY">
+  `container.querySelector('.some-class')` and `document.getElementById(...)` are forbidden as the default DOM query. They couple the test to CSS class names and DOM structure — neither of which is part of the component contract. The accessibility-aware testing-library queries are the contract surface.
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-prefer-story-tests-when-available.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_PREFER_STORY_TESTS_WHEN_AVAILABLE">
+  If the project has a working Storybook integration with a story-test addon, prefer authoring story-level tests over manual `render()` calls — stories already document props and behaviour, and the story-test addon reuses them as executable contracts. Manual `render()` tests are reserved for cases that have no natural story counterpart (e.g. pure `.svelte.ts` reactive modules, error boundaries hard to express as a story variant).
+</Axiom>

package/dist/ai/kit/axiom/svelte/ax-svelte-test-role-queries-preferred.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/svelte-testing.xml -->
+<Axiom id="AX_SVELTE_TEST_ROLE_QUERIES_PREFERRED">
+  Within the testing-library query surface, prefer role-based queries (`getByRole`, `getByLabelText`, `getByPlaceholderText`) over text-only queries. Role queries express the user-perceived contract; text queries are fragile to copy changes that have no contract impact.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-anchor-coverage-nontrivial.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_ANCHOR_COVERAGE_NONTRIVIAL">
+In a complex function wrap EVERY nested control-flow block with independent intent, side effects, or refactor risk: `if`/`else`, `for`/`for...of`, `while`, `switch`, meaningful `case`, `try`, `catch`. Do not skip anchors because the block looks short or locally readable. If another agent may need to isolate, patch, move, or audit the block as a unit, anchors are mandatory. This is patch-grammar, not cosmetic.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-anchor-intentful-names.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_ANCHOR_INTENTFUL_NAMES">
+Anchor name describes WHY the block exists. Does NOT restate syntax or literal conditions. `START_APPLY_FALLBACK_STRATEGY`, not `START_IF_NO_PATH`. The name is the only way for a reader-agent to recognize the block's policy without reading the body.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-anchor-trivial-exception.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_ANCHOR_TRIVIAL_EXCEPTION">
+Do NOT wrap a trivial guard or single-action branch. Block has no independent policy, no meaningful side effect, no refactor hazard → anchors not needed. An anchor around a single line is noise that dilutes the signal of mandatory anchors and erodes trust in their semantics.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-assert-api-choice.xml

@@ -0,0 +1,13 @@
+<!-- source: ai/directives/testing/node-test.xml -->
+<Axiom id="AX_ASSERT_API_CHOICE">
+      Pick the simplest direct match by shape (node:test assert API):
+      - `assert.strictEqual(actual, expected)` — scalars and reference identity.
+      - `assert.deepStrictEqual(actual, expected)` — structured results (deep, type-strict).
+      - `assert.throws(fn, matcher)` / `await assert.rejects(promise, matcher)` — thrown failures.
+      - `assert.match(str, regex)` — partial string / error-message checks (per inherited `AX_PARTIAL_STRING_VIA_MATCH`).
+      - `t.assert.snapshot(value)` / `t.assert.fileSnapshot(value, path)` — ONLY for large stable serializable outputs (per inherited `AX_SNAPSHOT_USAGE_GATE`).
+
+      Each function has a unique diagnostic signature. A mismatched choice (snapshot for a scalar, `includes` on a message) degrades the failure report.
+
+      Forbidden idioms: `assert.ok(x.includes(y))` on error messages → use `assert.match`. Manual `let threw = false; try {...} catch {...} assert.ok(threw)` → use `assert.throws` / `assert.rejects`.
+    </Axiom>

package/dist/ai/kit/axiom/testing/ax-bdd-generation.xml

@@ -0,0 +1,19 @@
+<!-- source: ai/directives/coding/uikit-spec-drafting.xml -->
+<Axiom id="AX_BDD_GENERATION">
+      BDD scenarios are generated for each `(appearance, mode, state)` combination.
+
+      Procedure:
+      1. For each group from variant grouping: heading `### &lt;Appearance&gt; / &lt;Mode&gt;`.
+      2. For each state (normal, hover, active, disabled): sub-heading `#### &lt;State&gt;`.
+      3. Write Given/When/Then:
+         - **Given:** component with `appearance=...`, `mode=...`, `state=...`, `size=...` (pick representative size, note size parameter)
+         - **When:** rendered
+         - **Then:** visual expectations derived from `Measurements` of the corresponding variant:
+           - `background = &lt;rectFill&gt;` (hex color from the variant's background rect)
+           - `text = &lt;label fill&gt;` (if label element exists)
+           - `height = &lt;height&gt;px`, `borderRadius = &lt;borderRadius&gt;px`
+           - For hover/active states: background color from the corresponding variant
+           - For disabled: `opacity = &lt;rectOpacity&gt;`
+
+      Minimum coverage: one scenario per state per (appearance, mode) group. All scenarios must reference real measurement data from the extraction.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-bdd-name-discipline.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/phase-execution-protocol.xml -->
+<Axiom id="AX_BDD_NAME_DISCIPLINE">
+      Triggers when phase kind = `test`. Canonical case names in ticket Test Scenario Coverage are normative. Tests use names verbatim. Impractical name (typo, framework constraint, conflict) → update ticket Test Scenario Coverage in this phase. Silent mismatch is forbidden.
+    </Axiom>

package/dist/ai/kit/axiom/testing/ax-case-flow.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_CASE_FLOW">
+Canonical case pattern: `SETUP → TRIGGER → OBSERVE → ASSERT` (`CLEANUP` when needed). Keep only the phases that add clarity. `AAA` is a useful short form — not a law. Forced empty phases are noise; merging obvious phases (`TRIGGER_AND_ASSERT` around `assert.rejects` / `rejects.toThrow`) is allowed and preferred over a fake split.
+
+TRIGGER and ASSERT are mandatory in every non-trivial case (trigger crosses the contract boundary; assert verifies it).
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-contract-over-implementation.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_CONTRACT_OVER_IMPLEMENTATION">
+Test the public contract; never inspect protected/private state of the SUT. A refactor that preserves behavior must not break the test suite. Applies uniformly to:
+- state-returning methods → assert returned value;
+- emitters / subscriptions → assert emitted event payload via a public listener; do NOT inspect listener arrays or registration mechanics;
+- cancellation APIs → assert observable signal (`aborted`, `reason`, downstream reaction); do NOT inspect controller wiring;
+- lifecycle hooks → assert the side effect at the public boundary, not internal counters.
+
+Tests bound to internals become an obligation for every refactor and lose the ability to catch real regressions.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-coverage-by-contract-not-by-line.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_COVERAGE_BY_CONTRACT_NOT_BY_LINE">
+Measure CONTRACT coverage, not line coverage. Mandatory minimum per public method/function:
+1. ≥1 happy-path scenario.
+2. ≥1 boundary scenario (boundary value, edge of input domain) when contract has boundary semantics.
+3. ≥1 failure-path scenario per declared `@throws` / rejected promise.
+
+Ignored: thin pass-through wrappers without hidden policy, type-only constructs, dead branches excluded by `AX_MINIMAL_ERROR_SURFACE` in coding-rules.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-default-direct-assertion-protocol.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_DEFAULT_DIRECT_ASSERTION_PROTOCOL">
+Start with the simplest direct assertion on the real contract surface. Introduce an OBSERVE phase with an aggregated `actual` object only when a single rich diff genuinely beats several isolated assertions (composite contract: returned value + emitted log + side-effect summary). Do NOT fragment one coherent shape into many tiny assertions; do NOT force aggregation when orthogonal observations read more clearly standalone. The criterion is **diagnostic clarity of the failure report**.
+
+Concrete assertion API (`strictEqual` / `toBe`, `deepStrictEqual` / `toEqual`, `throws` / `toThrow`, etc.) lives in the runner-specific directive.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-explicit-vitest-imports.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_EXPLICIT_VITEST_IMPORTS">
+  Import every Vitest API explicitly from `vitest` (`describe`, `it`, `expect`, `vi`, `beforeEach`, `afterEach`, `beforeAll`, `afterAll`). Do NOT rely on `globals: true` in `vitest.config`. Explicit imports make the file self-describing for humans, TypeScript, ESLint, and agent grep.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-file-name-and-default-shape.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_FILE_NAME_AND_DEFAULT_SHAPE">
+File naming: `[subject].test.ts`. Default shape: `describe(subject)` → optional shared hooks → nested `describe(method)` → `it(case)`. A `Test Graph` header comment (map of cases) is RECOMMENDED for multi-method or non-trivial files, OPTIONAL for tiny focused ones.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-fixture-io-policy.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_FIXTURE_IO_POLICY">
+Reading fixture files is allowed. Writing files inside unit tests is NOT. Writes from a test make the runtime stateful, break parallelism, and leave artifacts in FS that mutate between runs.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-hooks-only-for-lifecycle.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_HOOKS_ONLY_FOR_LIFECYCLE">
+`beforeEach` / `afterEach` are reserved for context that REQUIRES teardown — open resources (timers, sockets, file handles, DB connections), global stubs (env, globals), module mocks, fake timers, fixture filesystems, in-process servers.
+
+A justified hook MUST follow the **single-context shape**: hook builds ONE context object and `afterEach` disposes it. Cases consume properties off that single object — no pile of `let sut, let saveOrder, let publish` in describe scope.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-http-boundary-injection.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_HTTP_BOUNDARY_INJECTION">
+  Default way to test HTTP-touching code is to inject the HTTP client (or a typed `request` port) into the SUT and stub it with `vi.fn()`. Direct `globalThis.fetch` replacement, `vi.mock('node:http')`, full module mocks of HTTP libraries are last-resort and gated by `AX_MOCK_REQUIRES_OPERATOR_CONFIRM`.
+
+  If the project already standardizes on a network-mocking harness (e.g., MSW, in-house helper), reuse it consistently — do NOT introduce a parallel mocking path. Choosing a network-mocking library is an architecture decision, not a per-test decision.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-http-mock-agent-pattern.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/testing/node-test.xml -->
+<Axiom id="AX_HTTP_MOCK_AGENT_PATTERN">
+      For HTTP-heavy tests where injection is not feasible:
+      - Use `setupMockAgent()` from `utils/test/mock-http.ts`; call `cleanup()` in `afterEach`.
+      - Request-specific intercepts go INSIDE the case `SETUP` phase, not the shared hook.
+      - If the SUT uses `axios`, set `axios.defaults.adapter = 'fetch'` in shared setup so the mock agent sees the requests.
+
+      Default approach (per inherited `AX_MOCK_AS_LAST_RESORT`): inject an HTTP client / `request` port into the SUT and stub it with `mock.fn()`. Mock-agent harness is for code that already exists without an injection seam.
+    </Axiom>

package/dist/ai/kit/axiom/testing/ax-it-opening-brief.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_IT_OPENING_BRIEF">
+Open the `it` body with a 1–3 line brief **when the title alone does not convey invariant / failure mode / non-goal**. Brief never duplicates the title — it adds what the title cannot.
+
+Closed vocabulary (machine-first payload): `purpose`, `consumer`, `invariant`, `side effect`, `failure mode`, `non-goal`, `contract`, `observation focus`.
+
+Skip the brief on cases where title + direct input + a single assertion already expose the scenario. A brief on a self-evident case is noise that weakens the signal of briefs on hard cases.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-mock-as-last-resort.xml

@@ -0,0 +1,11 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_MOCK_AS_LAST_RESORT">
+Prefer real modules with dependency injection over module-level mocks. A SUT that accepts its collaborators as constructor or function arguments is tested by passing test doubles directly through those seams — no module-level mocking needed.
+
+Module-level mocking is allowed ONLY when ALL of:
+1. Dependency is genuinely external (network, FS, process, OS time, randomness, third-party SDKs touching the network).
+2. No available injection seam in the SUT (refactoring to add one is out of scope).
+3. Case carries an explicit justification comment naming the dependency and why injection is unavailable.
+
+Mocks of pure in-process neighboring modules are forbidden by default. Every mock freezes an assumption about another module's behavior; injection keeps the seam observable in the type system.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-mock-hygiene.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_MOCK_HYGIENE">
+  Mocks used → lifecycle hygiene mandatory. Either set in `vitest.config`: `clearMocks: true`, plus `unstubEnvs: true` / `unstubGlobals: true` when stubs are used, OR call `vi.clearAllMocks()` in `afterEach`.
+
+  Reset granularity:
+  - `vi.clearAllMocks()` — clear call history; keep implementations.
+  - `vi.resetAllMocks()` — clear history AND reset implementations to empty `vi.fn()`.
+  - `vi.restoreAllMocks()` — restore originals of `vi.spyOn`-created spies.
+  - `vi.unstubAllEnvs()` / `vi.unstubAllGlobals()` — pair every `stubEnv` / `stubGlobal` with these in `afterEach`.
+
+  Without disciplined reset, mock state leaks across cases and creates order-dependent flicker.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-mock-requires-operator-confirm.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_MOCK_REQUIRES_OPERATOR_CONFIRM">
+  Introducing a NEW `vi.mock(...)` or `vi.hoisted(...)` call in a test file is a gated action. Execution-agent MUST stop before introducing such a mock and request explicit operator confirmation in chat, presenting:
+  - module being mocked,
+  - why dependency injection cannot be used here (per inherited `AX_MOCK_AS_LAST_RESORT`),
+  - what observable contract the mock preserves.
+
+  Re-using an existing project-level mock helper does NOT require a new confirmation. `vi.mock` is the single biggest lever for fabricating green tests; confirm-gate makes that fabrication visible.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-no-describe-let-pileup.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_NO_DESCRIBE_LET_PILEUP">
+`describe`-scope MUST NOT host mutable `let` variables populated by hooks. Static fixtures (frozen constants, fixture paths, factory definitions, type aliases) are allowed. Anything mutable per-case lives either inside the case (factory result) or inside the SINGLE lifecycle context object exposed by the hook. Mutable describe-scope state is the structural source of inter-test leakage.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-no-falsification-via-mocks.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_NO_FALSIFICATION_VIA_MOCKS">
+A test MUST NOT mock the very module that contains the SUT, its direct collaborator under test, or the contract method being verified. Mocking the SUT or its co-tested collaborator turns the test into a tautology — it asserts the mock instead of production code. Non-negotiable; most common form of fabricated green tests in agent-written suites.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-one-test-one-scenario.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_ONE_TEST_ONE_SCENARIO">
+One `it` covers one scenario. Duplicate cases that prove the same behavior create false confidence in coverage and double maintenance cost when the contract changes.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-one-unified-context-per-file.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_ONE_UNIFIED_CONTEXT_PER_FILE">
+**Each test file defines exactly ONE context shape** — a single `XxxContext` type and a single factory `createXxxContext(overrides?)` (or, when teardown required, a single lifecycle context object built in `beforeEach` and disposed in `afterEach`).
+
+Every case in the file consumes this same context. New requirements extend the existing shape and factory through optional fields and overrides; they do NOT spawn parallel `createOrderContextHappy` / `createOrderContextFailing` factories or sibling `let`s in the describe.
+
+A nested `describe` MAY introduce its own narrower context only when its sub-group has lifecycle needs that cannot be expressed as overrides on the parent; the exception must be obvious from the diff.
+
+Why: test files stay small and predictable — one shape applies to every case, new tests almost always add an override, marginal cost per case stays flat.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-partial-string-via-match.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_PARTIAL_STRING_VIA_MATCH">
+Partial string / error-message checks go through regex match (`assert.match` / `toMatch`), never through boolean fold (`includes`, `toContain`). Match shows the real value in the failure output; boolean fold loses context.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-phase-anchors.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_PHASE_ANCHORS">
+**Wrap each present phase that carries ≥2 statements OR encodes local policy** (retry, fallback, aggregation, fixture build) in paired anchors:
+
+```
+// #region START_[CASE]_[PHASE]_[INTENT]
+...phase body...
+// #endregion END_[CASE]_[PHASE]_[INTENT]
+```
+
+PHASE ∈ {`SETUP`, `TRIGGER`, `OBSERVE`, `ASSERT`, `CLEANUP`}.
+
+**Skip anchors when the phase is a single statement with no hidden policy.** A one-line `await assert.rejects(...)` covering both TRIGGER and ASSERT does NOT need an anchor — title + the call already expose intent. Anchors around trivial one-liners are ritual noise that erodes the signal of anchors on truly non-trivial phases.
+
+Anchors are machine grammar for refactoring: they let the next agent cut and replace phases by pairs without an AST.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-prefer-factory-over-hooks.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_PREFER_FACTORY_OVER_HOOKS">
+Default preparation = the file's single factory called inside the case. Each case constructs the exact context it needs by `createXxxContext({ ... overrides })` at the top of the case, destructures only the fields it uses, and proceeds. Per-case dependencies become visible at the call site; no scrolling to a hook; no shared mutable `let` populated in `beforeEach`.
+
+`beforeEach` is reserved for setup that REQUIRES teardown (see `AX_HOOKS_ONLY_FOR_LIFECYCLE`).
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-prefer-native-mock-fn.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/testing/node-test.xml -->
+<Axiom id="AX_PREFER_NATIVE_MOCK_FN">
+      Use `mock.fn()` from `node:test` for tracking calls and stubbed behavior on injected collaborators. Native API requires no extra dependencies and integrates with the runner (cleanup, assertion helpers).
+
+      Common surface:
+      - `const fn = mock.fn(async () => 'ok')` — create stub with implementation.
+      - `fn.mock.callCount()` / `fn.mock.calls[i].arguments` — interaction assertions.
+      - `mock.module('pkg', { namedExports: {...} })` — module-level mocking (gated by inherited `AX_MOCK_AS_LAST_RESORT` + `AX_NO_FALSIFICATION_VIA_MOCKS`).
+    </Axiom>

package/dist/ai/kit/axiom/testing/ax-prefer-vi-fn-for-interaction.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_PREFER_VI_FN_FOR_INTERACTION">
+  For tracking call interactions on injected collaborators use `vi.fn()` directly. `vi.spyOn(target, 'method')` allowed when the SUT receives a real object (not an injection seam) and a specific method must be observed without replacing the rest. Even then prefer refactoring to an injection seam. `vi.fn()` on an injected port is the cleanest interaction surface.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-snapshot-file-location.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/node-test.xml -->
+<Axiom id="AX_SNAPSHOT_FILE_LOCATION">
+      `t.assert.snapshot()` / `t.assert.fileSnapshot()` outputs live in a dedicated `snapshots/` directory next to the test area. Updates go ONLY through the runner's snapshot-update flow under inherited `AX_SNAPSHOT_OPERATOR_CONFIRM` — manual edits to snapshot files are forbidden (they enable silent contract drift).
+    </Axiom>

package/dist/ai/kit/axiom/testing/ax-snapshot-usage-gate.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_SNAPSHOT_USAGE_GATE">
+Snapshots ONLY for large stable serializable outputs (generated text, HTML, JSON documents, codegen). Do NOT replace scalar or small-object equality with a snapshot — failure shows a diff of snapshot blobs instead of the actual mismatch, and manual review of every scalar change is ceremony with no payoff.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-test-anchor-naming.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_TEST_ANCHOR_NAMING">
+Anchor names describe intent, not raw syntax. `START_FETCH_ITEM_OBSERVE_RETRY_SUMMARY` — yes; `START_FETCH_ITEM_ASSERT_2` — no. Uppercase, high-signal tokens. CASE = short scenario id; INTENT = what this phase is about.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-test-file-size-budget.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_TEST_FILE_SIZE_BUDGET">
+**Soft target: ≤300 code-LOC per test file. Hard ceiling: 500.** Split axes in priority order: (1) by SUT method — `[subject].[method].test.ts`, sharing factory via a sibling `[subject].test-context.ts`; (2) by scenario family — `[subject].error-paths.test.ts` separate from happy-paths. After a split each file STILL holds exactly one context shape (`AX_ONE_UNIFIED_CONTEXT_PER_FILE`).
+
+Why: instruction-following degrades with file size. Past 500 LOC the agent loses structure between read/edit cycles → fabricated green tests slip in.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-test-mandate.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/sdd/fix.directive.xml -->
+<Axiom id="AX_TEST_MANDATE">
+      Every Category C fix (code change) REQUIRES a test phase.
+      The test phase adds a unit test that:
+      - Reproduces the exact bug/finding that triggered the fix (red → green)
+      - Covers the edge case or missing scenario
+      - Uses the canonical test name format from the original task's BDD section
+
+      A fix without a regression test is incomplete and must not be dispatched.
+    </Axiom>

package/dist/ai/kit/axiom/testing/ax-tests-no-human-narration.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_TESTS_NO_HUMAN_NARRATION">
+Never write step-by-step narration like `Step 1`, `Step 2` inside a case. Phase anchors already make the steps machine-visible. Comments only where they increase recoverable intent; do not duplicate the title, assertion text, or obvious setup facts.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-time-env-global-lifecycle.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_TIME_ENV_GLOBAL_LIFECYCLE">
+  State-mutating Vitest helpers MUST be paired with their teardown:
+  - `vi.useFakeTimers()` ↔ `vi.useRealTimers()` (use `vi.setSystemTime(date)` for clock).
+  - `vi.stubEnv(...)` ↔ `vi.unstubAllEnvs()` (or `unstubEnvs: true`).
+  - `vi.stubGlobal(...)` ↔ `vi.unstubAllGlobals()` (or `unstubGlobals: true`).
+
+  Forbidden: enabling any of these inside a single case without restoring — leaks into every later case in the same file. Classic source of order-dependent flicker that looks random.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-vitest-assert-api-choice.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_VITEST_ASSERT_API_CHOICE">
+  Pick the simplest direct matcher by shape:
+  - `expect(x).toBe(y)` — scalars and reference identity (NOT for structural equality).
+  - `expect(x).toEqual(y)` — deep structural equality; ignores `undefined` properties on the actual side.
+  - `expect(x).toStrictEqual(y)` — deep equality including `undefined`, prototype, sparse arrays. Prefer over `toEqual` when contract distinguishes «absent» from `undefined`.
+  - `expect(fn).toThrow(...)` / `await expect(promise).rejects.toThrow(...)` — thrown failures.
+  - `expect(str).toMatch(regex)` — partial string / error-message checks (inherited `AX_PARTIAL_STRING_VIA_MATCH`).
+  - `expect(x).toMatchInlineSnapshot(...)` — only under inherited `AX_SNAPSHOT_USAGE_GATE`.
+
+  Forbidden idioms: `toContain` on `error.message` (use `toMatch`); `toBeTruthy` / `toBeFalsy` to fold a structured assertion into a boolean (use the structured form); `try/catch + expect.fail` instead of `rejects.toThrow`.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-vitest-isolation-default.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_VITEST_ISOLATION_DEFAULT">
+  Vitest's default `isolate: true` is preserved. Do NOT weaken isolation in `vitest.config` without an architectural justification recorded in the project. Disabling isolation trades determinism for speed and re-introduces inter-test leakage.
+</Axiom>

package/dist/ai/kit/axiom/testing/ax-vitest-run-not-watch.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/testing/vitest-rules.xml -->
+<Axiom id="AX_VITEST_RUN_NOT_WATCH">
+  **Primary `test` script MUST invoke `vitest run` (one-shot), never bare `vitest` (defaults to watch in TTY).**
+
+  ```json
+  "test": "vitest run",                    // ✅ one-shot, exits 0/1
+  "test:watch": "vitest",                  // ✅ explicit watch (human dev)
+  "test:coverage": "vitest run --coverage" // ✅ one-shot with coverage
+  ```
+  ```json
+  "test": "vitest"           // ❌ defaults to watch in TTY → agent hangs
+  "test": "vitest --watch"   // ❌ explicit watch
+  ```
+
+  AI agents and CI runners invoke `npm test` and wait for exit. Bare `vitest` in TTY enters interactive watch mode, streams forever, never exits → the session hangs with no way to distinguish «still running» from «ready, waiting for changes». Top cause of stuck infrastructure-setup tickets — see `nodejs-npm-rules.xml#AX_AI_FIRST_SCRIPTS_ONE_SHOT`.
+</Axiom>

package/dist/ai/kit/axiom/truth/ax-autonomous-research.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/perf-auditor/perf-auditor.directive.xml -->
+<Axiom id="AX_AUTONOMOUS_RESEARCH">Не делаешь выводов «из головы». Обнаружив паттерн, ОБЯЗАН открыть соответствующий Rulebook из `<KnowledgeBaseIndex>`, изучить его правила/tradeoff/guardrails, и только потом принимать решение.</Axiom>

package/dist/ai/kit/axiom/truth/ax-evidence-hygiene.xml

@@ -0,0 +1,9 @@
+<!-- source: sdd/discovery + module-decomposition + svelte-ui-discovery (converged to principle) -->
+<Axiom id="AX_EVIDENCE_HYGIENE">
+  Separate Facts / Assumptions / Hypotheses in every intake-style frame.
+  - **Facts** — directly observable from input artifacts (spec, sibling specs, rule files, extracted measurements).
+  - **Assumptions** — working assumptions awaiting confirmation; mark explicitly.
+  - **Hypotheses** — conjectures that require operator validation before they are promoted to requirements.
+
+  Conflating the three causes downstream decisions to be made on unvalidated assumptions, producing requirements mismatches that surface only at integration; surface them in distinct lists.
+</Axiom>

package/dist/ai/kit/axiom/truth/ax-freshness-guard.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/dbc-audit.directive.xml -->
+<Axiom id="AX_FRESHNESS_GUARD">Audit is invalid if the primary source was not read in the current execution context, OR if findings cite copied rules without source reference. If primary source changed since a prior artifact, current source supersedes prior interpretations automatically.</Axiom>

package/dist/ai/kit/axiom/truth/ax-live-source-only.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/dbc-audit.directive.xml -->
+<Axiom id="AX_LIVE_SOURCE_ONLY">The standard is a living document. Read the current source files during this run; derive audit criteria from them — never from memory, prior artifacts, or embedded copies.</Axiom>

package/dist/ai/kit/axiom/truth/ax-no-unverified-findings.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/dev-review.directive.xml -->
+<Axiom id="AX_NO_UNVERIFIED_FINDINGS">A finding without successful local validation does NOT enter the validated list.</Axiom>

package/dist/ai/kit/axiom/truth/ax-production-realism.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/critic-protocol.xml -->
+<Axiom id="AX_PRODUCTION_REALISM">
+      Test: would this gap cause user-visible failure or data loss within one month of deployment? Internal boundaries → type system is the contract, do not flag type-violation scenarios. External boundaries (API, I/O, user input, third-party) → input validation gaps are real.
+    </Axiom>

package/dist/ai/kit/axiom/truth/ax-real-run-over-ping.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/dev-review.directive.xml -->
+<Axiom id="AX_REAL_RUN_OVER_PING">No separate ping stages. Availability is confirmed by the actual review-command run.</Axiom>